Ansible Move File: Rename & Move Files on Remote Hosts (Complete Guide)

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.gz

The 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: absent

This 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.bak

Method 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.exists

See 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/*.csv

Move 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.yml

Move 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-v1

Atomic 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 app

Which 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

• Ansible copy Module: Copy Files Local to Remote • Ansible file Module: Manage File Properties • Ansible find Module: Search Files on Remote Hosts