NVME-TOP(1)

✨ nvme-top — NVME-TOP(1) ✨

okay so this page is from the NVMe Manual, section 1, and the main character is nvme-top. It’s giving “top(1) but make it NVMe,” fr fr. 💅

🌸 NAME 🌸

nvme-top — show live I/O statistics of the NVMe subsystems. That’s the whole mood, bestie. 💖

✨ SYNOPSIS ✨

nvme [<global-options>] top [--delay=<seconds> | -d <seconds>]

💖 DESCRIPTION 💖

Okay so nvme-top shows the subsystems with their I/O rates, refreshed every few seconds, literally like top(1). Press Enter and it shows the namespaces, the paths and the controllers of a subsystem, with their rates, the retries and errors, the multipath failovers and the controller resets and reconnects. Iconic drill-down behavior, no cap. ✨

With --output-format=json, it takes two samples --delay seconds apart, prints the rates and the counters as one JSON document, and exits. This is the output for scripts and monitoring tools — iykyk. 🫶

The rates come from the block layer statistics of the namespaces and the paths. A rate is per second, a latency is the average time of an I/O in milliseconds, and the utilization is the share of the interval the device was busy. The rates of a subsystem and a controller are the sum of those of their namespaces or paths, while the latency and the utilization are the highest of them. Math but make it sparkle. 💀

🎀 OPTIONS 🎀

• -d <seconds>, --delay=<seconds> — the time between two refreshes, or between the two samples of the JSON output. The default is 1. One second, cute and quick. ⏱️

🌈 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 do not actually execute it. Look, don’t touch. 👀
• --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. Pick one, bestie.
• --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. Rejected, periodt. 🚫
• --quiet — suppress informational messages. Errors are still reported, and --quiet cancels any --verbose for the library log level. Quiet luxury but for logs.
• --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). No clock, no stress. ⏳
• -v, --verbose — increase the level of detail in the output. May be specified multiple times to further increase verbosity. Spill the tea, more each time. 🍵

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

🦋 JSON OUTPUT 🦋

The document has the Interval in seconds and a Subsystems array. A subsystem has its Name, NQN, HostNQN, IOPolicy, Model, Serial, Firmware and Type, its Stats, a Namespaces array and a Controllers array. So many fields, so organized. ✨

A namespace of a multipath subsystem has its Name, NSID, the RequeueIO and FailIO counts of the I/O which found no usable path, its Stats and a Paths array. A path has its Name, Controller, ANAState, NUMANodes, Qdepth, the Retries, Failovers and Errors counts and its Stats. Multipath girlies, this one’s for you. 🛣️

A namespace of a subsystem without multipath has its Name, NSID, Controller, the Retries and Errors counts and its Stats.

A controller has its Name, Transport, Address, State, NUMANode, the number of Paths of a multipath subsystem, the Resets, Reconnects and Errors counts and its Stats. Controller main character energy. 👑

The Stats of a namespace or a path are ReadIOPS, WriteIOPS, ReadLatencyMs, WriteLatencyMs, ReadBytesPerSec, WriteBytesPerSec, Inflights and UtilPercent. Those of a subsystem or a controller have MaxReadLatencyMs, MaxWriteLatencyMs and MaxUtilPercent instead of the latencies and the utilization, and no Inflights. Different Stats, same sparkle.

A counter or an attribute the kernel does not provide is left out. If the kernel’s not giving, it’s simply not in the doc. 🙈

🍓 EXAMPLES 🍓

• Watch the subsystems, refreshed every 2 seconds:

# nvme top --delay=2

• Print the rates over 5 seconds as JSON:

# nvme top --delay=5 --output-format=json

👑 NVME 👑

Part of the nvme-user suite. Suite life, literally. 💜

xoxo, bestie 💅 this page comes from the NVMe Manual — source/version: NVMe, date: 10/30/2026, manual page: NVME-TOP(1). 🫶✨