Ansible Move File: Relocate Files Between Directories (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: installation
How to move files in Ansible between directories. Use copy+file modules, command module with mv, synchronize module. Practical YAML playbook examples for file relocation and renaming.
Ansible Move File: Relocate Files Between Directories (Complete Guide)
Moving files between directories is a common task in system administration, but Ansible doesn't have a dedicated "move" module. This guide covers all practical approaches to move files with Ansible, from the recommended copy+delete pattern to using the command module.
Why No ansible.builtin.move Module?
Ansible follows an idempotent design philosophy. A "move" operation is inherently non-idempotent — running it twice would fail because the source no longer exists after the first run. Instead, Ansible provides building blocks that you combine for safe, repeatable file operations.
Method 1: Copy + Delete Pattern (Recommended)
The safest and most idempotent approach uses ansible.builtin.copy to copy the file, then ansible.builtin.file to remove the original:
Key parameter: remote_src: true tells Ansible to copy between paths on the remote host (not from the control node).
Method 2: Command Module with mv
For simple moves where idempotency is handled by conditionals:
Move with creates/removes Guards
Use creates and removes parameters for built-in idempotency:
Method 3: Rename a File
Renaming is just moving to the same directory with a different name:
Method 4: Move Multiple Files with find + loop
Move all files matching a pattern:
Method 5: Move Directories
Move an entire directory tree:
Or with the command module:
Method 6: Move Files Between Remote Hosts
Use ansible.builtin.fetch + ansible.builtin.copy:
Comparison: Which Method to Use
| Method | Best For | Idempotent | Preserves Permissions | |--------|----------|------------|----------------------| | copy + delete | Single files, safety | ✅ Yes | ✅ Yes (set explicitly) | | command mv | Speed, large files | ⚠️ With guards | ✅ Yes | | synchronize | Directories | ✅ Yes | ✅ Yes | | fetch + copy | Cross-host | ✅ Yes | ✅ Yes | | find + loop | Pattern matching | ✅ Yes | ✅ Yes |
Common Mistakes
1. Forgetting remote_src
2. Not Checking Source Exists
3. Missing Target Directory
FAQ
How do I move a file in Ansible?
Use the copy module with remote_src: true to copy the file to the new location, then the file module with state: absent to remove the original. Alternatively, use ansible.builtin.command with mv and removes/creates guards for idempotency.
Why doesn't Ansible have a move module?
Ansible is designed for idempotent operations. A move operation is inherently non-idempotent because the source file no longer exists after the first run. The copy + delete pattern achieves the same result while being safely repeatable.
Can I move files between two remote hosts with Ansible?
Yes. Use ansible.builtin.fetch to download the file from the source host to the control node, then ansible.builtin.copy to upload it to the destination host. For directory synchronization, use ansible.posix.synchronize.
How do I rename a file in Ansible?
Renaming is moving a file within the same directory. Use ansible.builtin.command with mv /path/old-name /path/new-name and removes/creates guards, or the copy + delete pattern with remote_src: true.
How do I move multiple files matching a pattern?
Use ansible.builtin.find to locate files matching your pattern, register the results, then loop over them with copy + file delete. See the "Move Multiple Files" example above.
Conclusion
While Ansible lacks a dedicated move module, the copy + delete pattern provides a safe, idempotent approach for most scenarios. Use ansible.builtin.command with mv for performance-critical operations on large files, and ansible.posix.synchronize for directory moves.
Related Articles • Ansible Create Directory: file Module state=directory Guide • Ansible Delete File: Remove Files & Directories • Ansible Rename File: Move & Rename Files • ansible.builtin.find Module: Search Files by Pattern • Ansible Fetch Module: Copy Files from Remote Hosts
Category: installation