Ansible: Check if a File Exists

Introduction

Ansible is an Infrastructure as Code tool that lets a single control node monitor and manage a large number of remote hosts (servers).

Ansible uses playbooks to define a variety of tasks for the remote hosts to perform, including checking if files and folders exist.

This tutorial covers how to use the stat module in Ansible to check if files and folders exist on remote hosts.

Prerequisites

• Access to the command line / terminal window
• Ansible installed and configured (see our guides on Installing Ansible on Windows and Installing Ansible on Ubuntu)

Checking if a File Exists in Ansible

The easiest way to check if a file exists using Ansible is with the stat module.

The purpose of the stat module is to retrieve facts about files and folders and record them in a register. The stat module uses the following syntax:

---
- name: Playbook name
  hosts: all

  tasks:
  - name: Task name
    stat:
      path: [path to the file or directory you want to check]
    register: register_name

...

Where:

• stat: Declares that we are using the stat module.
• path: Declares the path to the file or folder we want to check.
• register: Provides the name of the register where the stat module saves file and folder details.

One of the values recorded in the register is exists. Combining this value with the debug module lets you display a message detailing whether a file or folder exists:

  - name: Task name
    debug:
      msg: "The file or directory exists"
    when: register_name.stat.exists

1. In the example playbook, the first task (Checking if a file exists) uses the stat module to retrieve facts about the test.txt file located in /home/example_folder on the remote host. It records these facts in a register called file_data.

2. The second task (Report if a file exists) uses the debug module to display a message. It checks the file_data register and uses the exists value as a condition for displaying a message. If the exists value is true, the module displays the message ‘The file or directory exists’.

3. The third task (Report a missing file) does the same, except it displays the message ‘The file or directory doesn’t exist’ if the exist value is false.

Running the playbook provides the following output:

The output tells us that the file does not, in fact, exist.

If you also want to check that the file in question is a regular file and not a folder, add the isreg value to the debug module condition:

  - name: Task name
    debug:
      msg: "The file or directory exists"
    when: register_name.stat.exists and register_name.stat.isreg

Checking if a Directory Exists in Ansible

Using Ansible to check if a directory exists is exactly the same as checking if a file exists. The only difference is that you use the isdir value to confirm the path to the specified directory:

  - name: Task name
    debug:
      msg: "The file or directory exists"
    when: register_name.stat.exists and register_name.stat.isdir

Running Ansible Tasks Depending on Whether Files and Folders Exist

There are times when you want to run or skip tasks in your playbook depending on whether certain files or folders exist.

For instance, if you have a playbook designed to create a file on every remote host, you want to skip those hosts where the file already exists to avoid creating duplicates.

To do this, use the file details retrieved by the stat module with the when argument to create conditions for running tasks:

---
- name: Playbook name
  hosts: all

  tasks:
  - name: Task name
    stat:
      path: [path to the file or directory you want to check]
    register: register_name

    - name: Task name 2
      file:
        path: [path to the file you want to create]
        state: touch
      when: not register_name.stat.exists

...

1. In the playbook above, the first task (Checking if a file exists) uses the stat module to retrieve the details of the test.txt file located in example_folder on the remote host.

2. The second task (Create a file if it doesn’t already exist) starts by checking the exists value in the register. If the value is true, the task is skipped and the playbook ends. If the value is false, the task is executed and it creates a new file called test.txt.

Conclusion

After following this tutorial you should have a working knowledge of using Ansible’s stat module. You can use the information retrieved by this module to check if files and folders exist, and even decide if tasks are performed or skipped.