Ansible Move File: Rename & Move Files on Remote Hosts (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: file-operations
How to move and rename files with Ansible. Use command mv, copy+file, or ansible.builtin.copy with remote_src.
Ansible Move File: Rename & Move Files on Remote Hosts (Complete Guide)
Ansible doesn't have a dedicated "move" module, but there are several reliable ways to move and rename files on remote hosts. This guide covers every approach with practical examples.
See also: Ansible Move File: Relocate Files Between Directories (Complete Guide)
Method 1: command + mv (Simplest)
- name: Move file to new location
ansible.builtin.command: mv /tmp/app.tar.gz /opt/releases/app.tar.gz
args:
removes: /tmp/app.tar.gz
creates: /opt/releases/app.tar.gzThe removes and creates parameters make it idempotent.
Method 2: copy + file (Ansible-Native)
- name: Copy file to new location
ansible.builtin.copy:
src: /tmp/config.yml
dest: /etc/app/config.yml
remote_src: true
owner: appuser
group: appuser
mode: '0644'
- name: Remove original file
ansible.builtin.file:
path: /tmp/config.yml
state: absentThis approach gives you control over ownership and permissions during the move.
See also: Ansible file Module: Create Files, Directories, Symlinks (Complete Guide)
Method 3: Rename a File
- name: Rename file
ansible.builtin.command: mv /etc/app/config.yml /etc/app/config.yml.bak
args:
removes: /etc/app/config.yml
creates: /etc/app/config.yml.bakMethod 4: Move with Stat Check (Conditional)
- name: Check if source file exists
ansible.builtin.stat:
path: /tmp/report.csv
register: source_file
- name: Move file if it exists
ansible.builtin.command: mv /tmp/report.csv /var/data/reports/report.csv
when: source_file.stat.existsSee also: Ansible Set File Permissions 755: chmod with file Module Guide
Move Multiple Files
- name: Find all log files to archive
ansible.builtin.find:
paths: /var/log/app/
patterns: "*.log"
age: "7d"
register: old_logs
- name: Move old logs to archive
ansible.builtin.command: "mv {{ item.path }} /var/archive/logs/"
loop: "{{ old_logs.files }}"
# Or move all files matching a pattern
- name: Move all CSV files to processing directory
ansible.builtin.shell: mv /tmp/incoming/*.csv /var/data/processing/
args:
removes: /tmp/incoming/*.csvMove with Backup
- name: Move config with timestamp backup
block:
- name: Create backup of existing config
ansible.builtin.copy:
src: /etc/app/config.yml
dest: "/etc/app/config.yml.{{ ansible_date_time.iso8601_basic_short }}"
remote_src: true
when: existing_config.stat.exists | default(false)
- name: Move new config into place
ansible.builtin.command: mv /tmp/new-config.yml /etc/app/config.yml
args:
removes: /tmp/new-config.ymlMove Directory
- name: Move entire directory
ansible.builtin.command: mv /opt/app-v1 /opt/app-archive/app-v1
args:
removes: /opt/app-v1
creates: /opt/app-archive/app-v1Atomic Move (Safe for Config Files)
- name: Atomic move — write to temp then move
block:
- name: Write new config to temp file
ansible.builtin.template:
src: app.conf.j2
dest: /etc/app/config.yml.tmp
owner: root
mode: '0644'
validate: /opt/app/validate-config %s
- name: Atomically replace config
ansible.builtin.command: mv /etc/app/config.yml.tmp /etc/app/config.yml
notify: reload appWhich Method Should You Use?
| Scenario | Best Method |
|---|---|
| Simple move/rename | command: mv with creates/removes |
| Move + change permissions | copy (remote_src) + file (absent) |
| Move with validation | Template to .tmp, then command: mv |
| Move if file exists | stat check + conditional command: mv |
| Move multiple files | find + loop + command: mv |
| Move with glob patterns | shell: mv *.log /archive/ |
FAQ
Does Ansible have a move module?
No. Ansible doesn't have a dedicated move/rename module. Use ansible.builtin.command: mv for simple moves, or ansible.builtin.copy with remote_src: true followed by ansible.builtin.file: state=absent for an Ansible-native approach with permission control.
How do I move a file in Ansible idempotently?
Use ansible.builtin.command: mv source dest with creates: dest and removes: source parameters. This ensures the command only runs if the source exists and the destination doesn't.
How do I rename a file with Ansible?
Use ansible.builtin.command: mv /path/old-name /path/new-name with creates and removes for idempotency. Renaming is just a move within the same directory.
Can I move files between remote hosts with Ansible?
Not directly. Use ansible.builtin.fetch to download from one host, then ansible.builtin.copy to upload to another. Or use ansible.posix.synchronize (rsync) for efficient transfers between hosts.
Conclusion
While Ansible lacks a dedicated move module, command: mv with creates/removes is the most straightforward approach. Use copy + file when you need permission changes, and stat checks for conditional moves.
Related Articles
Category: file-operations