Ansible file Module: Create Files, Directories, Symlinks (Complete Guide)

Ansible file Module: Create Files, Directories, Symlinks (Complete Guide)

The ansible.builtin.file module manages filesystem objects — create directories, set permissions, create symlinks, and remove files. It's one of the most commonly used modules in Ansible playbooks.

See also: Ansible Set File Permissions 755: chmod with file Module Guide

Create a Directory

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

Create Nested Directories

- name: Create nested directory tree
  ansible.builtin.file:
    path: /opt/myapp/config/ssl/certs
    state: directory
    owner: appuser
    group: appuser
    mode: '0755'
    recurse: false  # Only set perms on the leaf directory

Create Multiple Directories

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

Create an Empty File

- name: Create empty log file
  ansible.builtin.file:
    path: /var/log/myapp/app.log
    state: touch
    owner: appuser
    group: appuser
    mode: '0644'

Touch Without Changing Existing Content

- name: Ensure file exists (don't overwrite)
  ansible.builtin.file:
    path: /opt/myapp/.initialized
    state: touch
    modification_time: preserve
    access_time: preserve

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

Create Symlinks

- name: Create symlink for current version
  ansible.builtin.file:
    src: /opt/myapp/releases/v2.1.0
    dest: /opt/myapp/current
    state: link
    owner: appuser
    group: appuser
- name: Create symlink in /usr/local/bin
  ansible.builtin.file:
    src: /opt/myapp/current/bin/myapp
    dest: /usr/local/bin/myapp
    state: link

Hard Links

- name: Create hard link
  ansible.builtin.file:
    src: /opt/myapp/config/base.yml
    dest: /opt/myapp/config/active.yml
    state: hard

Set Permissions and Ownership

- name: Set file permissions
  ansible.builtin.file:
    path: /opt/myapp/bin/start.sh
    owner: appuser
    group: appuser
    mode: '0755'
- name: Set permissions recursively
  ansible.builtin.file:
    path: /opt/myapp/data
    owner: appuser
    group: appuser
    mode: '0750'
    recurse: true

Special Permissions

- name: Set SGID on shared directory
  ansible.builtin.file:
    path: /opt/shared
    state: directory
    mode: '2775'
    group: developers
- name: Set sticky bit on tmp
  ansible.builtin.file:
    path: /opt/myapp/tmp
    state: directory
    mode: '1777'

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

Remove Files and Directories

- name: Remove a file
  ansible.builtin.file:
    path: /tmp/old-config.yml
    state: absent
- name: Remove entire directory tree
  ansible.builtin.file:
    path: /opt/myapp/old-release
    state: absent

Set File Attributes

- name: Make file immutable (chattr +i)
  ansible.builtin.file:
    path: /etc/resolv.conf
    attributes: i

Conditional File Operations

- name: Check if config exists
  ansible.builtin.stat:
    path: /opt/myapp/config/custom.yml
  register: custom_config
- name: Create default config if custom doesn't exist
  ansible.builtin.file:
    path: /opt/myapp/config/default.yml
    state: touch
  when: not custom_config.stat.exists

Common Patterns

Deploy Application Directory Structure

- name: Full app deployment structure
  block:
    - name: Create base directories
      ansible.builtin.file:
        path: "{{ item.path }}"
        state: directory
        owner: "{{ item.owner | default('appuser') }}"
        group: "{{ item.group | default('appuser') }}"
        mode: "{{ item.mode | default('0755') }}"
      loop:
        - { path: /opt/myapp }
        - { path: /opt/myapp/releases }
        - { path: /opt/myapp/shared/config }
        - { path: /opt/myapp/shared/logs, mode: '0775' }
        - { path: /opt/myapp/shared/tmp, mode: '1775' }
- name: Link current release
      ansible.builtin.file:
        src: "/opt/myapp/releases/{{ app_version }}"
        dest: /opt/myapp/current
        state: link

Cleanup Old Files

- name: Find old log files
  ansible.builtin.find:
    paths: /var/log/myapp
    patterns: '*.log'
    age: 30d
  register: old_logs
- name: Remove old log files
  ansible.builtin.file:
    path: "{{ item.path }}"
    state: absent
  loop: "{{ old_logs.files }}"

file Module Parameters Reference

• path (required) — Target path • state — file, directory, link, hard, touch, absent • src — Source for links • owner — File owner • group — File group • mode — Permissions (e.g., '0755', 'u+rwx,g+rx,o+rx') • recurse — Apply owner/group/mode recursively (directories only) • attributes — File attributes (chattr flags) • follow — Follow symlinks (default: yes) • force — Force link creation even if source doesn't exist

FAQ

How do I create a directory in Ansible?

Use ansible.builtin.file with state: directory: ansible.builtin.file: path=/opt/myapp state=directory mode='0755'. Ansible automatically creates parent directories.

How do I set file permissions in Ansible?

Use the mode parameter on the file module: ansible.builtin.file: path=/opt/myapp/script.sh mode='0755'. Use octal notation (always quote it) or symbolic notation like u+rwx,g+rx.

What is the difference between touch and file state?

state: touch creates the file if it doesn't exist and updates timestamps (like the touch command). state: file only sets attributes on existing files — it fails if the file doesn't exist.

How do I create a symlink in Ansible?

Use state: link with src and dest: ansible.builtin.file: src=/opt/app/v2 dest=/opt/app/current state=link. Use state: hard for hard links.

How do I delete a file or directory in Ansible?

Set state: absent: ansible.builtin.file: path=/tmp/old-file state=absent. This works for files, directories (recursively), and symlinks.

Conclusion

The ansible.builtin.file module is essential for managing filesystem objects in Ansible. Use it to create directories, set permissions, manage symlinks, and clean up files — all idempotently.

Related Articles

• Ansible copy Module: Copy Files to Remote Hosts • Ansible template Module: Deploy Jinja2 Templates • Ansible find Module: Search for Files