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
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:
| Column | Description |
|---|---|
NAME |
Block device name |
FSTYPE |
Filesystem type |
SIZE |
Device or filesystem size |
FSUSE% |
Filesystem space used (mounted entries) |
MOUNTPOINT |
Mount path |
SMART |
SMART health (OK, DENIED, etc.) |
LABEL |
Volume label |
UUID |
Filesystem UUID |
MODEL |
Drive model |
SERIAL |
Drive serial |
DISCARD |
TRIM / discard support |
READ |
Current read throughput |
WRITE |
Current write throughput |
Use -o / --output to select columns (comma-separated) or -x / --exclude to omit columns.
Options
Output format
| Flag | Description |
|---|---|
-j, --json |
Print JSON instead of a table |
-b, --bytes |
Print sizes and throughput as raw byte counts |
-H, --si |
Use powers of 1000 (SI) instead of 1024 for sizes |
-R, --full |
Do not truncate long values to terminal width |
-o, --output |
Columns to include (default: all) |
-x, --exclude |
Columns to omit |
Filtering
| Flag | Description |
|---|---|
filter_patterns … |
Show rows matching any pattern (regex) |
-D, --match_devname_only |
Apply patterns to device names only |
-v, --invert_match |
Invert pattern match |
-F, -fo, --formated_only |
Only entries with a filesystem type |
-M, -mo, --mounted_only |
Only mounted devices |
-B, -bo, --best_only |
Shortest mount point per device |
-A, -ao, --active_only |
Only devices with read/write activity |
-P, --pseudo |
Include pseudo filesystems (tmpfs, nfs, cifs, …) |
--show_zero_size_devices |
Include zero-size devices |
Runtime
| Flag | Description |
|---|---|
-t, --timeout |
Subprocess timeout in seconds (default: 2) |
-w, --watch SECONDS |
Repeat output every SECONDS (watch mode) |
--sudo |
Run external commands via sudo (needed for SMART on many systems) |
--debug |
Print suppressed exceptions to stderr |
-V, --version |
Show version and exit |
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 so only busy devices are shown. Each refresh re-reads mounts, labels, UUIDs, and sizes (throughput iterators stay live across refreshes).
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--sudoif permission is denied. - 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).
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file statblk-1.42.tar.gz.
File metadata
- Download URL: statblk-1.42.tar.gz
- Upload date:
- Size: 27.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1e8026eb57ccbd991d794ff6d5fabf0b90cd003a700d7d8e04f915534c854f15
|
|
| MD5 |
a76eec99d6647bd7573a19fc5fa326b7
|
|
| BLAKE2b-256 |
77b9a3e2f51455feacdf74a229068f4752de0d6fecc1bd5be6ee5ed354b4314d
|
File details
Details for the file statblk-1.42-py3-none-any.whl.
File metadata
- Download URL: statblk-1.42-py3-none-any.whl
- Upload date:
- Size: 21.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b9739cd7ca8bb8ebe3a351c1f304d2313bbdfba97088a7dbe9e36b9b8a799ac9
|
|
| MD5 |
d995f0a2132cdb774a9bcda618e2bb83
|
|
| BLAKE2b-256 |
06303e6a4c41fba530003a257aa1af9eb761280e1a7450aaf312b765b798c483
|
