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, which also takes fractions. A trailing integer positional still works the same as before (whole seconds only, so a pattern like 0.5 stays a filter):

statblk -w 5       # update every 5 seconds
statblk -w 0.5     # twice a second
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)

Each table refresh starts with a watch(1)-style header, Every 2s on <hostname>: <date time>. On a terminal the screen is redrawn in place; when output is piped or redirected every refresh is kept, so the log reads top to bottom. With -j / -J, watch mode prints one compact JSON document per line (NDJSON) so a reader can parse each refresh as it arrives; single-run JSON stays indented.

After the first refresh, --active_only is enabled automatically on Linux so only busy devices are shown, unless you gave filter patterns: devices you named stay on screen even while idle (not on macOS, where throughput isn't available; -A still forces it). 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

Health check

--check runs once and prints only the rows that need attention; when everything is healthy it prints nothing, so cron only mails on trouble. Exit status:

A problem beats an unknown, and both kinds of rows are listed. Exit 3 exists so that "not checked" never looks like "healthy" in a sweep. For a space-only check use -x SMART; to skip a device that has no SMART at all (an SD card, a USB stick) filter it out, e.g. statblk --check -D -v mmcblk. FSUSE% and SMART are always added to the shown columns so you can see why a row failed; excluding one with -x turns that check off. Filters (-M, -B, patterns) and JSON output (-j / -J) work as usual, but filters narrow what is checked: -M and patterns skip disks with no mount of their own (md/LVM/ZFS/Ceph members, extra btrfs pool devices), so cluster sweeps should run plain --check. --check can't be combined with watch mode.

statblk --check || mail -s "disk alert on $(hostname)" ops@example.com   # cron
statblk --check -x SMART --max_use 80                                    # space only
mssh 'nodes[1-64]' 'statblk --check'                                     # whole cluster via multiSSH3

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). smartctl runs with -n standby, so spun-down drives are not woken (not even by watch mode); they show STANDBY until they're next awake. This is verified for SATA drives on the kernel's libata driver; drives behind USB enclosures or some RAID/SAS controllers may still spin up, because smartctl's device-type probe goes through the bridge. On a hardware disk where SMART can't be read the column says why (NO SMARTCTL, DENIED, UNKNOWN); it is blank for virtual devices.
• squashfs on loop devices (snap packages, AppImages) is hidden by default: these images are read-only and always 100% full. Use --show_squashfs to list them. Other loop devices, such as a mounted disk image, are always shown.
• 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