Ansible copy Module: Copy Files & Content to Remote Hosts (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: windows-automation
Complete guide to Ansible copy module (ansible.builtin.copy). Copy files and content to remote hosts with permissions, backup, and validate options.
How to copy files to remote hosts? I'm going to show you a live Playbook with some simple Ansible code. I'm Luca Berton and welcome to today's episode of Ansible Pilot
Ansible copy files to remote hosts Today we're talking about Ansible module copy. The full name is "ansible.builtin.copy" which means is part of the collection of modules "builtin" with ansible and shipped with it. This module is pretty stable and out for years. The purpose is to copy files to remote locations. Please note that the opposite is done by Ansible fetch module. For Windows target use Ansible win_copy module.
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 • report.txt
Conclusion Now you know how to Copy files to remote hosts with Ansible.
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
| 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:
How do I copy files between two remote hosts?
Use fetch + copy, or delegate:
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
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
| 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:
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
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
| 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.
Related Articles • Ansible Become Guide • Ansible Roles Guide • Ansible for Windows Guide
Category: windows-automation
Watch the video: Ansible copy Module: Copy Files & Content to Remote Hosts (Complete Guide) — Video Tutorial