dwww Home | Manual pages | Find package

NVME-FORMAT(1)                    NVMe Manual                    NVME-FORMAT(1)

NAME
       nvme-format - Format an NVMe device

SYNOPSIS
       nvme format <device> [--namespace-id=<nsid> | -n <nsid>]
                               [--lbaf=<lbaf> | -l <lbaf>]
                               [--block-size=<block size | -b <block size>]
                               [--ses=<ses> | -s <ses>] [--pil=<pil> | -p <pil>]
                               [--pi=<pi> | -i <pi>] [--ms=<ms> | -m <ms>]
                               [--reset | -r] [--force]
                               [--timeout=<timeout> | -t <timeout>]
                               [--output-format=<fmt> | -o <fmt>] [--verbose | -v]

DESCRIPTION
       For the NVMe device given, send an nvme Format Namespace admin command
       and provides the results.

       The <device> parameter is mandatory and may be either the NVMe character
       device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1).
       If the character device is given, and the controller does not support
       formatting of particular namespaces (ID_CTRL.FNA bit 0 enabled), then
       all namespaces will be formatted. If FNA is disabled, then the namespace
       identifier must be specified with the namespace-id option; specify a
       value of 0xffffffff to send the format to all namespaces. If the block
       device is given, the namespace identifier will default to the namespace
       ID of the block device given, but can be overridden with the same
       option.

       Note, the numeric suffix on the character device, for example the 0 in
       /dev/nvme0, does NOT indicate this device handle is the parent
       controller of any namespaces with the same suffix. The namespace
       handle’s numeral may be coming from the subsystem identifier, which is
       independent of the controller’s identifier. Do not assume any particular
       device relationship based on their names. If you do, you may irrevocably
       erase data on an unintended device.

       On success, the program will automatically issue BLKRRPART ioctl to
       force rescanning the namespaces. If the driver is recent enough, this
       will automatically update the physical block size. If it is not recent
       enough, you will need to remove and rescan your device some other way
       for the new block size to be visible, if the size was changed with this
       command.

OPTIONS
       -n <nsid>, --namespace-id=<nsid>
           Send the format command for the specified nsid. This can be used to
           override the default value for either character device (unspecified)
           or the block device (result from NVME_IOCTL_ID).

       -l <lbaf>, --lbaf=<lbaf>
           LBA Format: This field specifies the LBA format to apply to the NVM
           media. This corresponds to the LBA formats indicated in the Identify
           Namespace command. Conflicts with --block-size argument. Defaults to
           0.

       -b <block size>, --block-size=<block size>
           Block Size: This field is used to specify the target block size to
           format to. Potential lbaf values will be scanned and the lowest
           numbered will be selected for the format operation. Conflicts with
           --lbaf argument.

       -s <ses>, --ses=<ses>
           Secure Erase Settings: This field specifies whether a secure erase
           should be performed as part of the format and the type of the secure
           erase operation. The erase applies to all user data, regardless of
           location (e.g., within an exposed LBA, within a cache, within
           deallocated LBAs, etc). Defaults to 0.
           ┌───────┬────────────────────────────┐
           │ Value │ Definition                 │
           ├───────┼────────────────────────────┤
           │ 0     │ No secure erase operation  │
           │       │ requested                  │
           ├───────┼────────────────────────────┤
           │ 1     │ User Data Erase: All user  │
           │       │ data shall be erased,      │
           │       │ contents of the user data  │
           │       │ after the erase is         │
           │       │ indeterminate (e.g., the   │
           │       │ user data may be zero      │
           │       │ filled, one filled, etc).  │
           │       │ The controller may perform │
           │       │ a cryptographic erase when │
           │       │ a User Data Erase is       │
           │       │ requested if all user data │
           │       │ is encrypted.              │
           ├───────┼────────────────────────────┤
           │ 2     │ Cryptographic Erase: All   │
           │       │ user data shall be erased  │
           │       │ cryptographically. This is │
           │       │ accomplished by deleting   │
           │       │ the encryption key.        │
           ├───────┼────────────────────────────┤
           │ 3–7   │ Reserved                   │
           └───────┴────────────────────────────┘

       -p <pil>, --pil=<pil>
           Protection Information Location: If set to ‘1’ and protection
           information is enabled, then protection information is transferred
           as the first bytes of metadata. If cleared to ‘0’ and protection
           information is enabled, then protection information is transferred
           as the last bytes of metadata. Defaults to 0.

       -i <pi>, --pi=<pi>
           Protection Information: This field specifies whether end-to-end data
           protection is enabled and the type of protection information.
           Defaults to 0.
           ┌───────┬───────────────────────────┐
           │ Value │ Definition                │
           ├───────┼───────────────────────────┤
           │ 0     │ Protection information is │
           │       │ not enabled               │
           ├───────┼───────────────────────────┤
           │ 1     │ Protection information is │
           │       │ enabled, Type 1           │
           ├───────┼───────────────────────────┤
           │ 2     │ Protection information is │
           │       │ enabled, Type 2           │
           ├───────┼───────────────────────────┤
           │ 3     │ Protection information is │
           │       │ enabled, Type 3           │
           ├───────┼───────────────────────────┤
           │ 4–7   │ Reserved                  │
           └───────┴───────────────────────────┘

       -m <ms>, --ms=<ms>
           Metadata Settings: This field is set to ‘1’ if the metadata is
           transferred as part of an extended data LBA. This field is cleared
           to ‘0’ if the metadata is transferred as part of a separate buffer.
           The metadata may include protection information, based on the
           Protection Information (PI) field. Defaults to 0.

       -r, --reset
           Issue a reset after successful format. Must use the character device
           for this.

       --force
           Just send the command immediately without warning of the
           implications.

       -t <timeout>, --timeout=<timeout>
           Override default timeout value 600,000. In milliseconds.

       -o <fmt>, --output-format=<fmt>
           Set the reporting format to normal, json or binary. Only one output
           format can be used at a time.

       -v, --verbose
           Increase the information detail in the output.

EXAMPLES
       •   Format the device using all defaults:

               # nvme format /dev/nvme0n1

       •   Format namespace 1 with user data secure erase settings and
           protection information:

               # nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1

NVME
       Part of the nvme-user suite

NVMe                               05/02/2025                    NVME-FORMAT(1)

Generated by dwww version 1.16 on Mon Nov 9 14:27:06 CET 2026.