How to Check if a File Exists in Ansible (4 Methods)

How to Check if a File Exists in Ansible (4 Methods)

Checking whether a file exists before taking action is one of the most common patterns in Ansible. Here are four methods, from simplest to most flexible.

See also: Ansible stat Module: Check File Properties and Existence (Complete Guide)

Method 1: stat Module (Recommended)

- name: Check if config file exists
  ansible.builtin.stat:
    path: /etc/myapp/config.yml
  register: config_file
- name: Copy default config if missing
  ansible.builtin.copy:
    src: default-config.yml
    dest: /etc/myapp/config.yml
  when: not config_file.stat.exists

Method 2: stat with Multiple Properties

- name: Check file details
  ansible.builtin.stat:
    path: /opt/myapp/data.db
  register: db_file
- name: Fail if file is missing or empty
  ansible.builtin.assert:
    that:
      - db_file.stat.exists
      - db_file.stat.size > 0
    fail_msg: "Database file is missing or empty!"
- name: Show file info
  ansible.builtin.debug:
    msg: "File size: {{ db_file.stat.size }}, Owner: {{ db_file.stat.pw_name }}"
  when: db_file.stat.exists

See also: Ansible Check If Directory Exists: stat Module Guide

Method 3: find Module (Multiple Files)

- name: Find all backup files
  ansible.builtin.find:
    paths: /backup
    patterns: '*.sql.gz'
    age: -1d
  register: recent_backups
- name: Alert if no recent backups
  ansible.builtin.fail:
    msg: "No backups found from the last 24 hours!"
  when: recent_backups.matched == 0

Method 4: creates/removes Parameters

Some modules have built-in file existence checks:

- name: Run migration only if not already done
  ansible.builtin.command: /opt/myapp/migrate.sh
  args:
    creates: /opt/myapp/.migrated
- name: Clean up only if temp file exists
  ansible.builtin.command: rm -rf /tmp/build-artifacts
  args:
    removes: /tmp/build-artifacts

See also: Ansible win_stat: Check if File or Directory Exists on Windows (Examples)

Check if Directory Exists

- name: Check directory
  ansible.builtin.stat:
    path: /opt/myapp
  register: app_dir
- name: Handle based on type
  ansible.builtin.debug:
    msg: "Is directory: {{ app_dir.stat.isdir | default(false) }}"
  when: app_dir.stat.exists

Check Remote vs Local File

# Check on remote host (default)
- name: Check remote file
  ansible.builtin.stat:
    path: /etc/nginx/nginx.conf
  register: remote_file
# Check on control node
- name: Check local file
  ansible.builtin.stat:
    path: files/nginx.conf
  register: local_file
  delegate_to: localhost

FAQ

What is the best way to check if a file exists in Ansible?

Use ansible.builtin.stat with register, then check result.stat.exists in a when conditional. This is the standard, idempotent approach.

Can I check if a file exists on the Ansible control node?

Yes. Add delegate_to: localhost to the stat task to check files on the control node instead of the remote host.

How do I check if a file exists and is not empty?

Use stat and check both result.stat.exists and result.stat.size > 0 in your conditional.

Related Articles

• Ansible stat Module: Complete Guide • Ansible find Module: Search Files • Ansible file Module: Create and Manage Files

Method Comparison

| Method | Use Case | Returns | Idempotent | |---|---|---|---| | ansible.builtin.stat | Check any file attribute | Full stat info | Yes | | when: file is exists | Simple Jinja2 test | Boolean | Yes | | ansible.builtin.find | Search for files by pattern | List of files | Yes | | ansible.builtin.command: test -f | Quick shell check | Return code | No |

Complete Example: Conditional Configuration

- name: Deploy config based on file existence
  hosts: all
  become: true
  tasks:
    - name: Check if custom config exists
      ansible.builtin.stat:
        path: /etc/myapp/custom.conf
      register: custom_config
- name: Deploy default config (only if custom doesn't exist)
      ansible.builtin.template:
        src: default.conf.j2
        dest: /etc/myapp/custom.conf
        owner: root
        group: root
        mode: '0644'
      when: not custom_config.stat.exists
- name: Backup existing config before changes
      ansible.builtin.copy:
        src: /etc/myapp/custom.conf
        dest: /etc/myapp/custom.conf.bak
        remote_src: true
      when: custom_config.stat.exists

Check Multiple Files

    - name: Check if required files exist
      ansible.builtin.stat:
        path: "{{ item }}"
      register: required_files
      loop:
        - /etc/ssl/certs/server.crt
        - /etc/ssl/private/server.key
        - /etc/myapp/config.yml
- name: Fail if any required file is missing
      ansible.builtin.fail:
        msg: "Missing required file: {{ item.item }}"
      loop: "{{ required_files.results }}"
      when: not item.stat.exists

FAQ

Which method is best for checking file existence?

ansible.builtin.stat is the most versatile — it provides file size, permissions, timestamps, and more. Use it when you need file attributes beyond existence.

Can I check if a file exists on the control node?

Yes. Use delegate_to: localhost or ansible.builtin.stat with connection: local:

- name: Check local file
  ansible.builtin.stat:
    path: /local/path/file.txt
  delegate_to: localhost
  register: local_file

How do I check if a directory exists?

Use ansible.builtin.stat and check stat.isdir:

- name: Check directory
  ansible.builtin.stat:
    path: /var/log/myapp
  register: dir_check
- name: Create if missing
  ansible.builtin.file:
    path: /var/log/myapp
    state: directory
  when: not dir_check.stat.exists