ansible.windows.win_file module – Creates, touches or removes files or directories

Note

This module is part of the ansible.windows collection (version 3.3.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install ansible.windows.

To use it in a playbook, specify: ansible.windows.win_file.

Synopsis

  • Creates (empty) files, updates file modification stamps of existing files, and can create or remove directories.

  • Timestamp values are interpreted as local time on the target Windows system if no time zone offset is specified.

  • Unlike ansible.builtin.file, does not modify ownership, permissions or manipulate links.

  • For non-Windows targets, use the ansible.builtin.file module instead.

Parameters

Parameter

Comments

access_time

string

added in ansible.windows 3.4.0

The desired access time for the file or directory.

A DateTime string in the format specified by access_time_format.

The timestamp is interpreted as local time on the target system.

Timezone offsets are supported when included in the timestamp format. (for example, using z, zz or zzz format specifiers).

When unset, the default is preserve when state=[file, directory] and now when state=touch.

access_time_format

string

added in ansible.windows 3.4.0

The format to use when parsing access_time.

Defaults to yyyy-MM-dd HH:mm:ss.

See .NET DateTime format strings.

Default: "yyyy-MM-dd HH:mm:ss"

modification_time

string

added in ansible.windows 3.4.0

The desired modification time for the file or directory.

A DateTime string in the format specified by modification_time_format.

The timestamp is interpreted as local time on the target system.

Timezone offsets are supported when included in the timestamp format. (for example, using z, zz or zzz format specifiers).

When unset, the default is preserve when state=[file, directory] and now when state=touch.

modification_time_format

string

added in ansible.windows 3.4.0

The format to use when parsing modification_time.

Defaults to yyyy-MM-dd HH:mm:ss.

See .NET DateTime format strings.

Default: "yyyy-MM-dd HH:mm:ss"

path

aliases: dest, name

path / required

Path to the file being managed.

state

string

If directory, all immediate subdirectories will be created if they do not exist.

If file, the file will NOT be created if it does not exist, see the ansible.windows.win_copy or ansible.windows.win_template module if you want that behavior.

If absent, directories will be recursively deleted, and files will be removed.

If touch, an empty file will be created if the path does not exist, while an existing file or directory will receive updated file access and modification times (similar to the way touch works from the command line).

Choices:

  • "absent"

  • "directory"

  • "file"

  • "touch"

See Also

See also

ansible.builtin.file

The official documentation on the ansible.builtin.file module.

ansible.windows.win_acl

Set file/directory/registry/certificate permissions for a system user or group.

ansible.windows.win_acl_inheritance

Change ACL inheritance.

ansible.windows.win_owner

Set owner.

ansible.windows.win_stat

Get information about Windows files.

Examples

- name: Touch a file (creates if not present, updates modification time if present)
  ansible.windows.win_file:
    path: C:\Temp\foo.conf
    state: touch

- name: Remove a file, if present
  ansible.windows.win_file:
    path: C:\Temp\foo.conf
    state: absent

- name: Create directory structure
  ansible.windows.win_file:
    path: C:\Temp\folder\subfolder
    state: directory

- name: Remove directory structure
  ansible.windows.win_file:
    path: C:\Temp
    state: absent

- name: Touch a file and set modification and access times to now
  ansible.windows.win_file:
    path: C:\Temp\foo.conf
    state: touch
    modification_time: now
    access_time: now

- name: Set specific modification and access times for a file
  ansible.windows.win_file:
    path: C:\Temp\foo.conf
    state: touch
    modification_time: "2025-12-29 12:34:56"
    access_time: "2025-12-29 12:34:56"

- name: Set specific modification as UTC datetime
  ansible.windows.win_file:
    path: C:\Temp\foo.conf
    state: touch
    modification_time: "2025-12-29 12:34:56 +0"
    modification_time_format: "yyyy-MM-dd HH:mm:ss z"

- name: Create a directory and set the timestamps to now
  ansible.windows.win_file:
    path: C:\Temp\folder
    state: directory
    modification_time: now
    access_time: now

Authors

  • Jon Hawkesworth (@jhawkesworth)

  • Bishal Prasad (@bishalprasad321)