community.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 community.windows collection (version 2.2.0).
You might already have this collection installed if you are using the ansible package.
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 community.windows.
To use it in a playbook, specify: community.windows.win_format.
Synopsis
The community.windows.win_format module formats an existing volume or a new volume on an existing partition on Windows
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. |
|
Enable compression on the resulting NTFS volume. 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. |
|
Used to specify the file system to be used when formatting the target volume. Choices:
|
|
Specify if formatting should be forced for volumes that are not created from new partitions or if the source and target file system are different. 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. Choices:
|
|
Used to specify the label of the volume to be formatted. |
|
Specifies that large File Record System (FRS) should be used. Choices:
|
|
Used to specify the new file system label of the formatted volume. |
|
Used to specify the path to the volume to be formatted. |
Notes
Note
Microsoft Windows Server 2012 or Microsoft Windows 8 or newer is required to use this module. To check if your system is compatible, see https://docs.microsoft.com/en-us/windows/desktop/sysinfo/operating-system-version.
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.
This module is idempotent if force is not specified and file system labels remain preserved.
For more information, see https://docs.microsoft.com/en-us/previous-versions/windows/desktop/stormgmt/format-msft-volume
See Also
See also
- community.windows.win_disk_facts
Show the attached disks and disk information of the target host.
- community.windows.win_partition
Creates, changes and removes partitions on Windows Server.
Examples
- name: Create a partition with drive letter D and size 5 GiB
community.windows.win_partition:
drive_letter: D
partition_size: 5 GiB
disk_number: 1
- name: Full format the newly created partition as NTFS and label it
community.windows.win_format:
drive_letter: D
file_system: NTFS
new_label: Formatted
full: True