ansible.windows.win_format module – Formats an existing volume or a new volume on an existing partition on Windows
Note
This module is part of the ansible.windows collection (version 3.9.1).
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_format.
New in ansible.windows 3.10.0
Synopsis
The ansible.windows.win_format module formats an existing volume or a new volume on an existing partition on Windows.
Use ansible.windows.win_format_info to gather information about volumes.
Parameters
Parameter |
Comments |
|---|---|
Specifies the cluster size to use when formatting the volume. If no cluster size is specified when you format a partition, defaults are selected based on the size of the partition. This value must be a multiple of the physical sector size of the disk. This value must be greater than zero. If the current allocation unit size of an already formatted volume cannot be determined, force is required. |
|
Enable compression on the resulting NTFS volume. Can only be specified for NTFS volumes. NTFS compression is not supported where allocation_unit_size is more than 4096. Choices:
|
|
Used to specify the drive letter of the volume to be formatted. Specify a single letter without a colon. |
|
Used to specify the file system to be used when formatting the target volume. Choices:
|
|
Required to change the file system or allocation unit size of an already formatted volume, even when the volume contains no files. When specified, the volume is formatted even if its current settings already match. Formatting removes existing data. Choices:
|
|
A full format writes to every sector of the disk, takes much longer to perform than the default (quick) format, and is not recommended on storage that is thinly provisioned. Specify Choices:
|
|
Enable integrity streams on the resulting ReFS volume. Can only be specified for ReFS volumes, including when disabling integrity streams. Choices:
|
|
Used to specify the label of the volume to be formatted. If multiple volumes have this label, the module fails without formatting. Use drive_letter or path to select a single volume. |
|
Specifies that large File Record Segments (FRS) should be used. Can only be specified for NTFS volumes. Choices:
|
|
Used to specify the new file system label of the formatted volume. If omitted, the existing volume label is preserved, including when force is specified. For an already formatted volume, the label can be changed without formatting the volume unless force is specified. An empty string clears the volume label. |
|
Used to specify the path to the volume to be formatted. |
Notes
Note
Requires Windows Server 2016 or newer with the Storage PowerShell module.
One of three parameters (drive_letter, path and label) are mandatory to identify the target volume but more than one cannot be specified at the same time.
Changing only new_label does not remove existing data. Repeating the same label update is idempotent.
Options that affect formatting (full, compress, integrity_streams, and large_frs) require force when the target volume is already formatted.
For more information, see https://learn.microsoft.com/en-us/windows-hardware/drivers/storage/format-msft-volume
See Also
See also
- ansible.windows.win_format_info
Gather information about Windows volumes.
- ansible.windows.win_initialize_disk_info
Gather information about disks on Windows Server.
Examples
- name: Full format the newly created partition as NTFS and label it
ansible.windows.win_format:
drive_letter: D
file_system: ntfs
new_label: Formatted
full: true
- name: Change an existing volume label while preserving its files
ansible.windows.win_format:
drive_letter: D
new_label: Data
- name: Gather volume information
ansible.windows.win_format_info:
drive_letter: D
register: data_volume