diskbench

Zero-dependency Python CLI tool for disk I/O benchmarking. Measures sequential and random read/write throughput, IOPS, and latency percentiles with OS cache bypass for accurate results.

Installation

pip install diskbench

Usage

# Run full benchmark suite against a directory
diskbench /tmp

# Quick single test
diskbench -t seq-write -i 1 -s 64M /tmp

# All options
diskbench [OPTIONS] PATH

Options

Option	Description
-s, --size SIZE	Test file size (default: 1G). Supports K/M/G/T suffixes.
-b, --block-size SIZE	Override block size (default: 1M sequential, 4K random)
-t, --tests TESTS	Comma-separated: seq-write,seq-read,rand-write,rand-read,all
-i, --iterations N	Iterations per test (default: 3)
--cached	Allow OS page cache (default: cache bypassed)
--no-cleanup	Keep test files after completion
--warmup	Run warmup pass before measurement
--json	Output as JSON
--csv	Output as CSV
-q, --quiet	Suppress progress output
-v, --verbose	Show per-iteration details
--version	Show version

Example output

================================================================================
diskbench v0.1.0 results
================================================================================
Target:     /tmp
File size:  1.00 GB | Cache: bypassed | Iterations: 3
--------------------------------------------------------------------------------

Test           Block     Throughput       IOPS    Lat p50    Lat p95    Lat p99
               Size          (MB/s)                  (us)       (us)       (us)
────────────── ───────── ────────── ────────── ────────── ────────── ──────────
seq-write      1.00 MB      2145.32       2145     425.30     892.10    1523.70
seq-read       1.00 MB      3201.18       3201     287.50     612.40     998.20
rand-write     4.00 KB       85.43      21870      42.10      98.50     245.30
rand-read      4.00 KB      124.67      31915      28.70      72.30     189.40

How it works

• Cache bypass: Uses fcntl(F_NOCACHE) on macOS and O_DIRECT on Linux
• Aligned I/O: Page-aligned buffers via mmap with libc pread/pwrite on Linux
• Accurate timing: time.perf_counter_ns() for nanosecond-precision per-operation latency
• Reproducible: Random offsets seeded with seed=42
• Best-of-N: Reports throughput/IOPS from the best iteration; latency percentiles from that run

Supported platforms

• macOS (Apple Silicon and Intel)
• Linux (x86_64, aarch64)

License

MIT