statblk

Gather disk and partition information for block devices and print it as a table or JSON.

Supports Linux and macOS.

Install

From PyPI:

pip install statblk

From a clone of this repository:

pip install .

Optional shell tab completion:

pip install 'statblk[completion]'

Requires Python 3.6+ and the multiCMD package (>= 1.47).

Quick start

statblk
statblk -j                    # JSON output (rows, header first)
statblk -J                    # JSON objects with numeric sizes/rates
statblk -o NAME,SIZE,MOUNTPOINT
statblk sda nvme              # filter rows matching sda or nvme
statblk 2                     # refresh every 2 seconds (watch mode)

Output columns

By default every column that has data is shown (a column that is empty for every row, such as LABEL when nothing is labelled, is hidden from the table):

Use -o / --output to select columns (comma-separated) or -x / --exclude to omit columns. Columns named with -o are always shown, even when empty; --show_empty_columns keeps empty columns in the default view. JSON output (-j / -J) always includes every selected column.

Options

Output format

Filtering

Runtime

Watch mode

Prefer -w / --watch. A trailing integer positional still works the same as before:

statblk -w 5       # update every 5 seconds
statblk 5          # same (trailing integer)
statblk sda 3      # filter to sda, refresh every 3 seconds
statblk -w 3 sda   # same with explicit flag (flag wins if both are given)

After the first refresh, --active_only is enabled automatically on Linux so only busy devices are shown (not on macOS, where throughput isn't available). Each refresh re-reads mounts, labels, UUIDs, sizes, and per-drive sysfs info such as model/serial, so hot-swapped drives show up correctly (throughput iterators stay live across refreshes). Press Ctrl-C to stop (exit status 130).

If a filter pattern looks like a number, append 0 so it is not treated as the refresh interval (or use -w and keep the number as a filter):

statblk nvme0 0    # match nvme0, single run (no watch)
statblk -w 0 nvme0 # same via flag

Platform notes

Linux

Uses sysfs, /proc/self/mountinfo, lsblk, and optionally smartctl.

• SMART requires smartctl (smartmontools). Use --sudo if permission is denied. It only runs against hardware-backed disks (not loop, dm, md, zram, nbd). The column is hidden when no disk reports SMART; use -o or --show_empty_columns to show it and --debug to see why it is empty.
• autofs trigger mounts are ignored (stat-ing them would trigger the automount); the real filesystem appears once mounted.
• READ / WRITE throughput comes from /sys/class/block/*/stat (always 512-byte sector units).
• On a single-shot run (and the first row of watch mode), READ/WRITE are a lifetime busy-time average (bytes / time spent in I/O since boot). In watch mode, later refreshes are interval rates over the sleep period (Δbytes / wall clock).

macOS

Uses diskutil and mount. Throughput columns are always zero (no per-device sysfs stats). APFS snapshot nodes such as the sealed system volume (disk3s1s1 on /) are listed.

Development

Install test deps:

pip install -r requirements-dev.txt

Run unit tests (default; live excluded) and embedded doctests:

pytest
python -m doctest statblk.py -v
python statblk.py --doctest

Optional live checks:

pytest -m live          # soft smoke on this host
pytest -m live_strict   # compare FSUSE% and names to df/lsblk

License

GPLv3+ — Yufei Pan (pan@zopyr.us)

Project home: github.com/yufei-pan/statblk