Ansible copy Module: Copy Files to Remote Hosts (ansible.builtin.copy Guide)

By Luca Berton · Published 2024-01-01 · Category: windows-automation

How to copy files to remote hosts with Ansible copy module (ansible.builtin.copy). Transfer files, set permissions, use content parameter, backup.

Ansible copy Module: Copy Files to Remote Hosts (ansible.builtin.copy Guide)

How to copy files to remote hosts?

ansible.builtin.copy copies files, directories, and inline string content from the Ansible controller to remote hosts over SSH. It is idempotent — files are only transferred when content or permissions differ — and supports checksum validation, atomic backup creation, and SELinux context management.

The opposite operation (downloading from remote to controller) is done by the Ansible fetch module. For Windows targets use the Ansible win_copy module.

Ansible copy module — ansible.builtin.copy

Parameters

dest _path_ - remote path
src _string_ - local path
backup _boolean_ - no / yes
validate _string_ - validation command
checksum _string_ 2.5+
mode/owner/group
setype/seuser/selevel

The parameter list is pretty wide but I'll summarize the most useful.

The only required parameter is "dest" which specifies the remote absolute path destination.

The "src" specifies the source file in the controller host. It could be a relative or absolute path. I recommend absolutely.

The backup boolean option allows you to create a backup if the utility overwrites any file.

If there is any tool to validate the file we could specify it in the validate parameter, very useful for configuration files.

Let me also highlight that we could also specify the permissions and SELinux properties.

Demo

Let's jump in a real-life playbook to copy files to remote hosts with Ansible.

code

copy.yml

---
- name: copy module Playbook
  hosts: all
  become: false
  tasks:
    - name: copy report.txt
      ansible.builtin.copy:
        src: report.txt
        dest: /home/devops/report.txt
        owner: devops
        mode: '0644'

report.txt

test report.txt

code with ❤️ in GitHub

Conclusion

Now you know how to Copy files to remote hosts with Ansible.

Advanced Copy Examples

Copy with backup

- name: Deploy config with automatic backup
  ansible.builtin.copy:
    src: files/nginx.conf
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
    backup: true  # Saves existing file as .backup
  become: true
  notify: reload nginx

Copy entire directory

- name: Copy directory to remote
  ansible.builtin.copy:
    src: files/app/    # Trailing slash copies CONTENTS
    dest: /opt/myapp/
    owner: appuser
    group: appuser
    mode: '0755'
  become: true

# Without trailing slash: copies the directory itself
# src: files/app → creates /opt/myapp/app/
# src: files/app/ → copies contents into /opt/myapp/

Validate before replacing

- name: Copy and validate nginx config
  ansible.builtin.copy:
    src: files/nginx.conf
    dest: /etc/nginx/nginx.conf
    validate: /usr/sbin/nginx -t -c %s
  become: true
  # Only replaces if nginx -t passes

Copy with content from variable

- name: Generate hosts file entry
  ansible.builtin.copy:
    content: |
      {% for host in groups['webservers'] %}
      {{ hostvars[host].ansible_host }} {{ host }}
      {% endfor %}
    dest: /etc/hosts.d/webservers
    mode: '0644'
  become: true

Remote-to-remote copy (using remote_src)

- name: Copy file on remote host
  ansible.builtin.copy:
    src: /var/log/app.log
    dest: /backup/app.log.bak
    remote_src: true  # Source is on the remote host
  become: true

copy vs synchronize vs template

Module	Use Case	Speed
`copy`	Single files, small directories	Moderate
`synchronize`	Large directories (rsync)	Fast
`template`	Files needing Jinja2 rendering	Moderate
`fetch`	Remote → controller (reverse copy)	Moderate

For directories with many files, synchronize (rsync) is significantly faster than copy.

Key Parameters

Parameter	Description
`src`	Local source path
`dest`	Remote destination path
`content`	Write text content directly
`mode`	File permissions
`owner` / `group`	File ownership
`backup`	Create backup of existing file
`force`	Overwrite if content differs (default: true)
`remote_src`	Source is on remote host
`validate`	Command to validate file before replacing
`directory_mode`	Permissions for created directories

FAQ

Why is copy slow for large files?

Ansible copy calculates checksums and transfers via SSH/SFTP. For large files or many files, use synchronize (rsync) instead:

- name: Sync large directory
  ansible.posix.synchronize:
    src: /local/large-dir/
    dest: /remote/large-dir/

How do I copy files between two remote hosts?

Use fetch + copy, or delegate:

- name: Fetch from source
  ansible.builtin.fetch:
    src: /data/export.csv
    dest: /tmp/
    flat: true
  delegate_to: source_server

- name: Copy to destination
  ansible.builtin.copy:
    src: /tmp/export.csv
    dest: /data/import.csv

Does copy preserve timestamps?

No — copy sets the modification time to the current time. Use synchronize with --times to preserve timestamps.

Copy File to Remote

- name: Copy config to remote
  ansible.builtin.copy:
    src: files/nginx.conf
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
  become: true

Copy with Backup

- copy:
    src: files/app.conf
    dest: /etc/myapp/app.conf
    backup: true  # Creates timestamped backup
  become: true

Copy Directory

# With trailing slash — copies CONTENTS
- copy:
    src: files/configs/
    dest: /etc/myapp/
  become: true

# Without trailing slash — copies the DIRECTORY itself
- copy:
    src: files/configs
    dest: /opt/
  become: true

Copy Between Remote Paths

- copy:
    src: /opt/myapp/config.yml
    dest: /opt/myapp/config.yml.bak
    remote_src: true
  become: true

Inline Content

- copy:
    content: |
      DB_HOST={{ db_host }}
      DB_PORT={{ db_port }}
      APP_ENV={{ env }}
    dest: /etc/myapp/.env
    mode: '0600'
  become: true

Copy Multiple Files

- copy:
    src: "{{ item.src }}"
    dest: "{{ item.dest }}"
    mode: "{{ item.mode | default('0644') }}"
  loop:
    - { src: nginx.conf, dest: /etc/nginx/nginx.conf }
    - { src: php.ini, dest: /etc/php/8.2/fpm/php.ini }
    - { src: deploy.sh, dest: /opt/scripts/deploy.sh, mode: '0755' }
  become: true
  notify: restart services

Conditional Copy

- copy:
    src: "configs/{{ env }}.conf"
    dest: /etc/myapp/config.conf
  become: true

# Or with when
- copy:
    src: files/ssl.conf
    dest: /etc/nginx/conf.d/ssl.conf
  when: enable_ssl | default(false)
  become: true

Validate Before Placing

- copy:
    src: files/nginx.conf
    dest: /etc/nginx/nginx.conf
    validate: "nginx -t -c %s"
  become: true

- copy:
    src: files/sudoers
    dest: /etc/sudoers
    validate: "visudo -cf %s"
  become: true

Force and Idempotency

# Only copy if file doesn't exist
- copy:
    src: files/initial-config.yml
    dest: /etc/myapp/config.yml
    force: false  # Don't overwrite existing
  become: true

# Always overwrite (default)
- copy:
    src: files/config.yml
    dest: /etc/myapp/config.yml
    force: true
  become: true

copy vs synchronize vs template

Module	Best For
`copy`	Single/few files, inline content
`synchronize`	Large directory trees (rsync)
`template`	Files with Jinja2 variables/logic
`fetch`	Copy FROM remote TO controller
`get_url`	Download from HTTP/HTTPS

Key Parameters

Parameter	Description
`src`	Source file/dir on controller
`dest`	Destination on remote
`content`	Inline content (instead of src)
`owner`/`group`	File ownership
`mode`	Permissions
`backup`	Keep backup of original
`force`	Overwrite if different
`remote_src`	Source is on remote host
`validate`	Validation command
`directory_mode`	Mode for created directories
`follow`	Follow symlinks

FAQ

How do I copy from remote to local?

Use the fetch module:

- fetch:
    src: /var/log/app.log
    dest: /tmp/logs/{{ inventory_hostname }}/
    flat: true

Large files are slow — alternatives?

Use synchronize (rsync wrapper) for large files or directories — it's significantly faster.

Why does copy show "changed" every run?

Check file permissions — if mode doesn't match, Ansible reports a change. Always specify mode explicitly.

Copy a File

- ansible.builtin.copy:
    src: files/app.conf
    dest: /etc/myapp/app.conf
  become: true

With Permissions

- copy:
    src: files/app.conf
    dest: /etc/myapp/app.conf
    owner: appuser
    group: appgroup
    mode: '0644'
  become: true

Write Content Directly

- copy:
    content: |
      [database]
      host = db.example.com
      port = 5432
    dest: /etc/myapp/db.conf
    mode: '0644'
  become: true

Copy Directory

- copy:
    src: files/configs/   # Trailing slash = copy contents
    dest: /etc/myapp/
  become: true

- copy:
    src: files/configs    # No trailing slash = copy directory itself
    dest: /etc/myapp/
  become: true

Backup Before Overwrite

- copy:
    src: files/nginx.conf
    dest: /etc/nginx/nginx.conf
    backup: true  # Creates .bak file
  become: true
  notify: reload nginx

Don't Overwrite Existing

- copy:
    src: files/default.conf
    dest: /etc/myapp/config.conf
    force: false  # Skip if dest exists
  become: true

Validate Before Deploy

# Validate nginx config
- copy:
    src: files/nginx.conf
    dest: /etc/nginx/nginx.conf
    validate: "nginx -t -c %s"
  become: true

# Validate sudoers
- copy:
    src: files/sudoers
    dest: /etc/sudoers.d/myapp
    validate: "visudo -cf %s"
    mode: '0440'
  become: true

Copy from Remote to Remote

# remote_src copies on the remote host itself
- copy:
    src: /opt/backup/config.conf
    dest: /etc/myapp/config.conf
    remote_src: true
  become: true

Copy with Variable Content

- copy:
    content: "{{ lookup('template', 'config.j2') }}"
    dest: /etc/myapp/config.conf
  become: true

copy vs template vs synchronize

Module	Use Case
`copy`	Static files, small content
`template`	Dynamic files with Jinja2
`synchronize`	Large directories (rsync)
`fetch`	Remote → controller (reverse copy)

FAQ

copy vs fetch?

copy sends files controller→remote. fetch pulls files remote→controller.

How to copy to multiple hosts?

Just target multiple hosts — copy runs on each host in the play.

Large files slow?

Use synchronize (rsync wrapper) for large files or many files — it's much faster than copy.

Category: windows-automation

Watch the video: Ansible copy Module: Copy Files to Remote Hosts (ansible.builtin.copy Guide) — Video Tutorial

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton

Ansible copy Module: Copy Files to Remote Hosts (ansible.builtin.copy Guide)

How to copy files to remote hosts?

Ansible copy module — ansible.builtin.copy

Parameters

Demo

code

Conclusion

Advanced Copy Examples

Copy with backup

Copy entire directory

Validate before replacing

Copy with content from variable

Remote-to-remote copy (using remote_src)

copy vs synchronize vs template

Key Parameters

FAQ

Why is copy slow for large files?

How do I copy files between two remote hosts?

Does copy preserve timestamps?

Copy File to Remote

Copy with Backup

Copy Directory

Copy Between Remote Paths

Inline Content

Copy Multiple Files

Conditional Copy

Validate Before Placing

Force and Idempotency

copy vs synchronize vs template

Key Parameters

FAQ

How do I copy from remote to local?

Large files are slow — alternatives?

Why does copy show "changed" every run?

Copy a File

With Permissions

Write Content Directly

Copy Directory

Backup Before Overwrite

Don't Overwrite Existing

Validate Before Deploy

Copy from Remote to Remote

Copy with Variable Content

copy vs template vs synchronize

FAQ

copy vs fetch?

How to copy to multiple hosts?

Large files slow?

Related Articles