# win_format – Formats an existing volume or a new volume on an existing partition on Windows

New in version 2.8.

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Status

## 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

Choices:
- no
- yes

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

Choices:
- ntfs
- refs
- exfat
- fat32
- fat

Used to specify the file system to be used when formatting the target volume.

force
boolean

Choices:
- no
- yes

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

Choices:
- no
- yes

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

Choices:
- no
- yes

Enable integrity streams on the resulting ReFS volume.

label string |  | Used to specify the label of the volume to be formatted.

large_frs
boolean

Choices:
- no
- yes

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]

### Authors

- Varun Chopra (@chopraaa) <v@chopraaa.com>

Hint

If you notice any issues in this documentation, you can edit this document to improve it.