NVME-FORMAT(1)

📦
version 3.2 · 14 versions
, in arch rolling

💅 NVME-FORMAT 💅

okay bestie, this is the nvme-format page from the NVMe Manual — yes, that one, the "please don't nuke my drive" one. Buckle up 🎀

✨ NAME ✨

nvme-format — Format an NVMe device

🌸 SYNOPSIS 🌸

nvme [<global-options>] 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]

🦋 DESCRIPTION 🦋

So for the NVMe device you hand it, this bad boy sends an nvme Format Namespace admin command and gives you back the results. Slay. ✨

The <device> parameter is mandatory — like, non-negotiable — and it can be either the NVMe character device (ex: /dev/nvme0) or a namespace block device (ex: /dev/nvme0n1). Here's the tea on how it behaves:

  • If you give it the character device and the controller does not support formatting of particular namespaces (ID_CTRL.FNA bit 0 enabled), then all namespaces get formatted.
  • If FNA is disabled, then you must specify the namespace identifier with the namespace-id option — or pass a value of 0xffffffff to send the format to all namespaces.
  • If you give it the block device, the namespace identifier defaults to the namespace ID of the block device you gave, but you can override it with that same option. 💖
⚠️ okay listen, this next part is SO important. The numeric suffix on the character device — like the 0 in /dev/nvme0 — does NOT mean 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. 😭😭😭 I am not joking, bestie. That is your whole life's work gone. fr fr.

On success, the program will automatically issue a 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'll need to remove and rescan your device some other way for the new block size to be visible — that's only if the size was changed with this command, no cap.

⭐ 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 the character device (which is unspecified) or the block device (which is the result from NVME_IOCTL_ID). The broadcast value 0xffffffff can also be given as all or -1. 👑
  • -l <lbaf>, --lbaf=<lbaf> — LBA Format: this field specifies the LBA format to apply to the NVM media. It corresponds to the LBA formats indicated in the Identify Namespace command. Conflicts with the --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 one will be selected for the format operation. Conflicts with the --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.

So the values are giving:

  • 0 — No secure erase operation requested
  • 1 — User Data Erase: all user data shall be erased, and the 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. 💜

The values, bestie:

  • 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. It's 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 one. ⭐
  • --force — Just send the command immediately without warning of the implications. 💀 (yes that's the whole description. iconic honestly.)

👑 GLOBAL OPTIONS 👑

The following options are defined at the top-level nvme command and are available to this subcommand:

  • --dry-run — Print the command that would be executed, but don't actually execute it. 🙈
  • --no-ioctl-probing — Disable probing for 64-bit IOCTL support.
  • --no-retries — Disable retry logic on transient errors.
  • -o <fmt>, --output-format=<fmt> — Set the reporting format to normal, tabular, json, or binary. Only one output format may be used at a time. 🌈
  • --output-format-version=<version> — Select the output format version. Version 1 uses the original field naming, while version 2 (default) provides more consistent and script-friendly field names. Other versions are rejected. 🫶
  • --quiet — Suppress informational messages. Errors are still reported, and --quiet cancels any --verbose for the library log level.
  • --set-options=<key=value>[,<key=value>...] — Set libnvme library options for this invocation. Supported keys are force-4k, mi-probe-enabled, test-base-dir and test-sysfs-dir.
  • --timeout=<ms> — Set the timeout for the command in milliseconds. infinite or -1 waits without a time limit (0xffffffff). ⭐
  • -v, --verbose — Increase the level of detail in the output. May be specified multiple times to further increase verbosity. 💅

These options can also be set as machine-wide defaults in nvme-cli.conf(5). A command-line flag always overrides the file. ✨

🍓 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 💖

and that's the whole page, bestie — go forth and format responsibly 🎀 this was NVMe documentation, dated 10/30/2026, page NVME-FORMAT(1). mwah 💋

📦 where this page comes from