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 all columns are shown:

Use -o / --output to select columns (comma-separated) or -x / --exclude to omit columns.

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). Use --debug to see why the column 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