win_format – Formats an existing volume or a new volume on an existing partition on Windows¶
New in version 2.8.
Synopsis¶
The win_format module formats an existing volume or a new volume on an existing partition on Windows
Parameters¶
| Parameter | Choices/Defaults | Comments |
|---|---|---|
|
allocation_unit_size
integer
|
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.
|
|
|
compress
boolean
|
|
Enable compression on the resulting NTFS volume.
NTFS compression is not supported where allocation_unit_size is more than 4096.
|
|
drive_letter
string
|
Used to specify the drive letter of the volume to be formatted.
|
|
|
file_system
string
|
|
Used to specify the file system to be used when formatting the target volume.
|
|
force
boolean
|
|
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.
|
|
full
boolean
|
|
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
true for full format. |
|
integrity_streams
boolean
|
|
Enable integrity streams on the resulting ReFS volume.
|
|
label
string
|
Used to specify the label of the volume to be formatted.
|
|
|
large_frs
boolean
|
|
Specifies that large File Record System (FRS) should be used.
|
|
new_label
string
|
Used to specify the new file system label of the formatted volume.
|
|
|
path
string
|
Used to specify the path to the volume to be formatted.
|
Notes¶
Note
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
- win_disk_facts – Show the attached disks and disk information of the target host
The official documentation on the win_disk_facts module.
- win_partition – Creates, changes and removes partitions on Windows Server
The official documentation on the win_partition module.
Examples¶
- name: Create a partition with drive letter D and size 5 GiB
win_partition:
drive_letter: D
partition_size: 5 GiB
disk_number: 1
- name: Full format the newly created partition as NTFS and label it
win_format:
drive_letter: D
file_system: NTFS
new_label: Formatted
full: True
Status¶
This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]