community.windows.win_format_module.rst

community.windows.win_format

Formats an existing volume or a new volume on an existing partition on Windows

• Synopsis
• Parameters
• Notes
• See Also
• Examples
• Status

Synopsis

• The :ref:`community.windows.win_format <community.windows.win_format_module>` 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. This value must be a multiple of the physical sector size of the disk.
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

• 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

.. seealso::

   :ref:`community.windows.win_disk_facts_module`
      The official documentation on the **community.windows.win_disk_facts** module.
   :ref:`community.windows.win_partition_module`
      The official documentation on the **community.windows.win_partition** module.

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

Status

Authors

• Varun Chopra (@chopraaa) <[email protected]>