Ansible: Check if a File Exists

December 24, 2020

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.

Ansible check if a file exists

Prerequisites

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
Ansible satt module playbook template

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:

Stat module example playbook 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

Note: Many Infrastructure as Code (IaC) tools are available on the market. Terraform and Puppet and Pulumi are all popular IaC tools.

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

...
Using the stat module to skip tasks

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.

Was this article helpful?
YesNo
Aleksandar Kovačević
With a background in both design and writing, Aleksandar Kovacevic aims to bring a fresh perspective to writing for IT, making complicated concepts easy to understand and approach.
Next you should read
Ansible Playbook: How to Create and Configure Playbooks
December 17, 2020

Ansible is a Code as Infrastructure solution for monitoring and managing remote hosts. This is done by using...
Read more
Ansible Playbook Dry Run: Run Playbook in "Check Mode"
November 19, 2020

This article explains how to do a dry run of an Ansible playbook by using the built-in check mode feature.
Read more
How to Create a File in Ansible
October 7, 2020

Ansible allows you to quickly and easily use a single control node to manage a multiple remote servers. You...
Read more
How to Install and Configure Ansible on Ubuntu 20.04
September 10, 2020

Ansible is a management system that helps you manage a large number of servers without the need for any...
Read more