How to Check if a File Exists in Ansible (4 Methods)
By Luca Berton · Published 2024-01-01 · Category: database-automation
How to check if a file exists in Ansible using stat module, when conditional, and find module. Complete guide with playbook examples for file existence checks.
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.existsMethod 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.existsSee 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 == 0Method 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-artifactsSee 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.existsCheck 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: localhostFAQ
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.existsCheck 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.existsFAQ
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_fileHow 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.existsCategory: database-automation