Ansible Create Directory: file Module with state=directory (Guide)

How to create a directory with Ansible?

I'm going to show you a live Playbook and some simple Ansible code. I'm Luca Berton and welcome to today's episode of Ansible Pilot.

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

Ansible create a directory

> ansible.builtin.file: Manage files and file properties

Today we're talking about the Ansible module file. The full name is ansible.builtin.file, which means that is part of the collection of modules "builtin" with ansible and shipped with it. It's a module pretty stable and out for years. It works in a different variety of operating systems. It manages files and file properties. For Windows targets, use the ansible.windows.win_file module instead.

Parameters

• path string (dest, name) - file path • state string - file/absent/directory/hard/link/touch • mode/owner/group - permission • setype/seuser/selevel - SELinux

This module has some parameters to perform any tasks. The only required is "path", where you specify the filesystem path of the file you're going to edit. The state defines the type of object we are modifying, the default is "file" but for our use case, we need the "directory" option.

See also: Ansible Create Hard Link & Symlink: file Module Guide

Demo

Let's jump into a real-life playbook on how to create a directory with Ansible.

code

• create_directory.yml

---
- name: file module demo
  hosts: all
  vars:
    mydir: "~/example"
  tasks:
    - name: Creating a directory
      ansible.builtin.file:
        path: "{{ mydir }}"
        state: directory
        owner: devops
        group: users
        mode: '0644'

execution

$ ansible-playbook -i Playbook/inventory create\ directory/file.yml
PLAY [file module demo] *********************************************************************
TASK [Gathering Facts] **********************************************************************
ok: [demo.example.com]
TASK [Creating a directory] *****************************************************************
changed: [demo.example.com]
PLAY RECAP **********************************************************************************
demo.example.com           : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

before execution

$ ssh devops@demo.example.com
[devops@demo ~]$ ls -al
total 16
drwx------. 4 devops wheel  111 Nov 14 13:43 .
drwxr-xr-x. 5 root   root    50 Nov  8 17:07 ..
drwx------. 3 devops wheel   17 Sep  6 05:53 .ansible
-rw-------. 1 devops wheel 2849 Nov 14 13:43 .bash_history
-rw-r--r--. 1 devops wheel   18 Dec  4  2020 .bash_logout
-rw-r--r--. 1 devops wheel  141 Dec  4  2020 .bash_profile
-rw-r--r--. 1 devops wheel  376 Dec  4  2020 .bashrc
drwx------. 2 devops wheel   94 Sep 16 10:09 .ssh
[devops@demo ~]$

after execution

$ ssh devops@demo.example.com
[devops@demo ~]$ ls -al
total 16
drwx------. 5 devops wheel  126 Nov 14 13:45 .
drwxr-xr-x. 5 root   root    50 Nov  8 17:07 ..
drwx------. 3 devops wheel   17 Sep  6 05:53 .ansible
-rw-------. 1 devops wheel 2861 Nov 14 13:44 .bash_history
-rw-r--r--. 1 devops wheel   18 Dec  4  2020 .bash_logout
-rw-r--r--. 1 devops wheel  141 Dec  4  2020 .bash_profile
-rw-r--r--. 1 devops wheel  376 Dec  4  2020 .bashrc
drwx------. 2 devops wheel   94 Sep 16 10:09 .ssh
drw-r--r--. 2 devops users    6 Nov 14 13:45 example

code with ❤️ in GitHub

Conclusion

Now you know how to create a directory in Linux with Ansible.

See also: Ansible Create Symlink: file Module with state=link (Guide)

Create Single Directory

- name: Create application directory
  ansible.builtin.file:
    path: /opt/myapp
    state: directory
    owner: appuser
    group: appgroup
    mode: '0755'
  become: true

Create Nested Directories

# Creates all parent directories automatically (like mkdir -p)
- ansible.builtin.file:
    path: /opt/myapp/config/ssl/certs
    state: directory
    mode: '0755'
  become: true

Create Multiple Directories

- name: Create project structure
  ansible.builtin.file:
    path: "{{ item }}"
    state: directory
    owner: deploy
    group: deploy
    mode: '0755'
  loop:
    - /opt/myapp/bin
    - /opt/myapp/config
    - /opt/myapp/data
    - /opt/myapp/logs
    - /opt/myapp/tmp
  become: true

Directory with Specific Permissions

# Restricted directory
- ansible.builtin.file:
    path: /opt/myapp/secrets
    state: directory
    owner: root
    group: appgroup
    mode: '0750'  # Owner: rwx, Group: r-x, Other: ---
  become: true
# Sticky bit (shared directory)
- ansible.builtin.file:
    path: /opt/shared
    state: directory
    mode: '1777'  # Like /tmp
  become: true
# SGID (files inherit group)
- ansible.builtin.file:
    path: /opt/project
    state: directory
    group: developers
    mode: '2775'
  become: true

Create from Variable

- vars:
    app_dirs:
      - { path: /opt/myapp, mode: '0755' }
      - { path: /opt/myapp/config, mode: '0750' }
      - { path: /opt/myapp/logs, mode: '0775' }
      - { path: /opt/myapp/secrets, mode: '0700' }
  ansible.builtin.file:
    path: "{{ item.path }}"
    state: directory
    owner: appuser
    mode: "{{ item.mode }}"
  loop: "{{ app_dirs }}"
  become: true

Check if Directory Exists

- name: Check directory
  ansible.builtin.stat:
    path: /opt/myapp
  register: dir_check
- name: Create only if missing
  ansible.builtin.file:
    path: /opt/myapp
    state: directory
  when: not dir_check.stat.exists
  become: true

Set Permissions Recursively

- ansible.builtin.file:
    path: /opt/myapp
    state: directory
    owner: appuser
    group: appgroup
    recurse: true
  become: true

Windows Directory

- name: Create Windows directory
  ansible.windows.win_file:
    path: C:\Program Files\MyApp\config
    state: directory

FAQ

Does state: directory create parent directories?

Yes — like mkdir -p, it creates all parent directories that don't exist.

Why quote mode as '0755'?

YAML interprets unquoted 0755 as decimal 493. Always use quotes for octal permissions: mode: '0755'

How do I delete a directory?

- ansible.builtin.file:
    path: /opt/old-app
    state: absent
  become: true

This removes the directory and all its contents recursively.

Create Directory

- ansible.builtin.file:
    path: /opt/myapp
    state: directory
  become: true

Create with Permissions

- file:
    path: /opt/myapp
    state: directory
    mode: '0755'
    owner: deploy
    group: deploy
  become: true

Create Nested Directories

# Creates all parent directories automatically
- file:
    path: /opt/myapp/config/ssl/certs
    state: directory
    mode: '0755'
  become: true

Create Multiple Directories

- file:
    path: "{{ item }}"
    state: directory
    mode: '0755'
    owner: deploy
  loop:
    - /opt/myapp/bin
    - /opt/myapp/config
    - /opt/myapp/data
    - /opt/myapp/logs
    - /opt/myapp/tmp
  become: true

Application Directory Structure

- name: Create application directory structure
  file:
    path: "{{ item.path }}"
    state: directory
    mode: "{{ item.mode }}"
    owner: "{{ item.owner | default('appuser') }}"
  loop:
    - { path: /opt/myapp, mode: '0755' }
    - { path: /opt/myapp/bin, mode: '0755' }
    - { path: /opt/myapp/config, mode: '0750' }
    - { path: /opt/myapp/config/ssl, mode: '0700' }
    - { path: /opt/myapp/data, mode: '0755' }
    - { path: /opt/myapp/logs, mode: '0755' }
    - { path: /var/run/myapp, mode: '0755' }
  become: true

Conditional Creation

- stat:
    path: /opt/myapp
  register: app_dir
- file:
    path: /opt/myapp
    state: directory
  when: not app_dir.stat.exists
  become: true

Temporary Directory

- ansible.builtin.tempfile:
    state: directory
    prefix: myapp_
  register: tmpdir
- debug:
    msg: "Temp dir: {{ tmpdir.path }}"

SGID Directory (Group Inheritance)

# New files inherit the group
- file:
    path: /opt/shared
    state: directory
    mode: '2775'
    group: developers
  become: true

Remove Directory

- file:
    path: /opt/old-app
    state: absent
  become: true

Ensure Directory Tree from Variable

- vars:
    app_dirs:
      base: /opt/myapp
      subdirs:
        - bin
        - etc
        - var/log
        - var/run
        - share/doc
  file:
    path: "{{ app_dirs.base }}/{{ item }}"
    state: directory
    mode: '0755'
  loop: "{{ app_dirs.subdirs }}"
  become: true

FAQ

Does state=directory create parents?

Yes — like mkdir -p, Ansible creates all parent directories. You don't need to create them separately.

What happens if the directory exists?

The module is idempotent. If the directory exists with correct permissions, it reports ok (no change). If permissions differ, it corrects them and reports changed.

How to create directory only if a condition is met?

Use when:

- file:
    path: /opt/myapp/cache
    state: directory
  when: enable_cache | default(false)

Create a Directory

- ansible.builtin.file:
    path: /opt/myapp
    state: directory
  become: true

With Permissions

- file:
    path: /opt/myapp
    state: directory
    mode: '0755'
    owner: appuser
    group: appgroup
  become: true

Recursive (Create Parent Dirs)

- file:
    path: /opt/myapp/data/logs/archive
    state: directory
    recurse: true  # Creates all parent dirs
  become: true

Multiple Directories

- file:
    path: "{{ item }}"
    state: directory
    mode: '0755'
  loop:
    - /opt/myapp
    - /opt/myapp/data
    - /opt/myapp/logs
    - /opt/myapp/config
  become: true

Directory Structure from Variable

- file:
    path: "/opt/myapp/{{ item.path }}"
    state: directory
    mode: "{{ item.mode | default('0755') }}"
    owner: "{{ item.owner | default('root') }}"
  loop:
    - { path: data, owner: appuser }
    - { path: logs, mode: '0775' }
    - { path: config, mode: '0700' }
    - { path: tmp, mode: '1777' }
  become: true

Check If Directory Exists

- stat:
    path: /opt/myapp
  register: dir_check
- file:
    path: /opt/myapp
    state: directory
  when: not dir_check.stat.exists
  become: true

Remove a Directory

- file:
    path: /opt/old-app
    state: absent  # Recursively removes directory and contents
  become: true

Set Permissions Recursively

- file:
    path: /opt/myapp
    state: directory
    recurse: true
    owner: appuser
    group: appgroup
  become: true

Temporary Directory

- tempfile:
    state: directory
    prefix: myapp_
  register: temp_dir
- debug:
    msg: "Temp dir: {{ temp_dir.path }}"

FAQ

file module vs command mkdir?

file module is idempotent (safe to run repeatedly), sets ownership/permissions atomically, and reports changed correctly. Always prefer file over command: mkdir.

recurse vs creating parents?

recurse: true sets permissions on existing contents. For creating parent dirs, the file module creates them automatically when state: directory.

How to create a directory only if a file exists?

- stat: { path: /opt/flag-file }
  register: flag
- file: { path: /opt/new-dir, state: directory }
  when: flag.stat.exists

Related Articles

• Ansible inventory best practices • role-based playbook organization in Ansible • state=absent with ansible.builtin.file • Ansible for Windows Guide