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

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

The ansible.builtin.stat module retrieve file or filesystem status. This guide covers all common use cases with practical playbook examples.

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

Check if a File Exists

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

Get File Properties

- name: Get file info
  ansible.builtin.stat:
    path: /opt/myapp/release.tar.gz
  register: file_info
- name: Show file details
  ansible.builtin.debug:
    msg: |
      Size: {{ file_info.stat.size }} bytes
      Owner: {{ file_info.stat.pw_name }}
      Mode: {{ file_info.stat.mode }}
      Modified: {{ file_info.stat.mtime }}

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

Verify File Checksum

- name: Get checksum
  ansible.builtin.stat:
    path: /opt/myapp/release.tar.gz
    checksum_algorithm: sha256
  register: file_stat
- name: Verify checksum matches
  ansible.builtin.assert:
    that:
      - file_stat.stat.checksum == expected_checksum
    fail_msg: "Checksum mismatch! Expected {{ expected_checksum }}"

Check if Path is a Directory

- name: Check path type
  ansible.builtin.stat:
    path: /opt/myapp
  register: path_info
- name: Create directory if not exists
  ansible.builtin.file:
    path: /opt/myapp
    state: directory
  when: not path_info.stat.exists or not path_info.stat.isdir

See also: Ansible Check if File Exists: stat Module with when Conditional (Guide)

Check File Age

- name: Get file stats
  ansible.builtin.stat:
    path: /var/log/myapp/app.log
  register: log_stat
- name: Rotate if older than 7 days
  ansible.builtin.command: /opt/scripts/rotate-logs.sh
  when: (ansible_date_time.epoch | int) - (log_stat.stat.mtime | int) > 604800

Common stat Fields

The stat result contains these useful fields: • stat.exists — whether the path exists • stat.isdir — is it a directory • stat.isreg — is it a regular file • stat.islnk — is it a symbolic link • stat.size — file size in bytes • stat.uid / stat.gid — owner/group IDs • stat.pw_name / stat.gr_name — owner/group names • stat.mode — permissions (e.g., "0644") • stat.checksum — file checksum (when requested) • stat.mtime — last modified time (epoch) • stat.atime — last access time (epoch)

FAQ

How do I 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 idempotent way to conditionally create or modify files.

What is the difference between stat and file modules?

The stat module reads file information without changing anything. The file module creates, modifies, or deletes filesystem objects. Use stat for checks, file for changes.

How do I get a file checksum in Ansible?

Use ansible.builtin.stat with checksum_algorithm: sha256 (or md5, sha1). Access the result via result.stat.checksum.

Conclusion

The ansible.builtin.stat module is a versatile tool for retrieve file or filesystem status. Use the examples above as starting points and adapt them to your infrastructure needs.

Related Articles

• Ansible file Module: Manage Files and Directories • Ansible find Module: Search for Files