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.
- 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
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 ...
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
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
Note: Many Infrastructure as Code (IaC) tools are available on the market. Ansible, Terraform, 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 ...
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
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.