Ansible copy Module: Copy Files Local to Remote (ansible.builtin.copy Guide)
By Luca Berton · Published 2024-01-01 · Category: database-automation
Complete guide to Ansible copy module (ansible.builtin.copy). Copy files from local to remote, set permissions, backup, use content parameter. Practical YAML playbook examples.
Ansible copy Module: Copy Files Local to Remote (ansible.builtin.copy Guide)
The Ansible copy module (ansible.builtin.copy) is the primary way to transfer files from the Ansible control node to remote hosts. This guide covers every use case — from simple file copies to advanced patterns with permissions, backups, and validation.
Basic File Copy
Key Parameters
| Parameter | Description | Example | |-----------|-------------|---------| | src | Local source file path | files/app.conf | | dest | Remote destination path | /etc/app/app.conf | | content | Inline content (instead of src) | "Hello World" | | owner | File owner | root | | group | File group | www-data | | mode | File permissions | '0644' | | backup | Create backup before overwriting | true | | remote_src | Copy between remote paths | true | | validate | Command to validate before placing | nginx -t -c %s | | force | Overwrite if different | true (default) | | directory_mode | Permissions for created directories | '0755' |
Copy with Content (Create File Inline)
Copy Entire Directory
Note: A trailing / on src copies the contents of the directory. Without it, the directory itself is copied inside dest.
Copy Between Remote Paths (remote_src)
Backup Before Overwriting
Validate Before Placing
Prevent deploying invalid configurations:
Conditional Copy (Only If Missing)
Copy with Variables in Filename
Copy Multiple Files with Loop
Copy with SELinux Context
copy vs template vs lineinfile
| Use Case | Module | |----------|--------| | Static file (no variables) | copy | | File with Jinja2 variables/logic | template | | Modify single line in existing file | lineinfile | | Modify block of text in existing file | blockinfile | | Create file with inline text | copy + content |
Common Mistakes
1. Forgetting remote_src for remote-to-remote copies
2. Mode as integer instead of string
3. Missing parent directory
Performance Tips
For large files or many files, consider: • ansible.posix.synchronize (rsync) for directories • ansible.builtin.get_url for files available via HTTP • ansible.builtin.unarchive for deploying archives
The copy module calculates checksums to avoid unnecessary transfers — it won't re-copy unchanged files.
FAQ
What is the Ansible copy module used for?
The ansible.builtin.copy module copies files from the Ansible control node to remote hosts. It can also create files with inline content using the content parameter, and copy between paths on the same remote host with remote_src: true.
How do I copy a file from local to remote with Ansible?
Use ansible.builtin.copy with src (local file path) and dest (remote destination path). Set owner, group, and mode for proper permissions.
What is the difference between Ansible copy and template?
The copy module transfers files as-is (or with inline content). The template module processes Jinja2 templates — use it when your file contains variables ({{ var }}), loops, or conditionals. Use copy for static files.
How do I copy files between directories on a remote host?
Set remote_src: true in the copy module. This tells Ansible to copy between paths on the remote host instead of from the control node.
Does Ansible copy overwrite existing files?
Yes, by default (force: true). Set force: false to only copy if the destination file doesn't exist. Use backup: true to create a timestamped backup before overwriting.
Conclusion
The Ansible copy module is essential for file deployment and configuration management. Use src/dest for file transfers, content for inline file creation, backup for safety, and validate for configuration verification. Always set proper owner, group, and mode permissions.
Related Articles • Ansible template Module: Deploy Jinja2 Templates • Ansible fetch Module: Copy Files from Remote Hosts • Ansible lineinfile Module: Add & Replace Lines in Files • Ansible synchronize Module: Rsync Files Between Hosts
Category: database-automation