CLI

Discover and run benchmarks defined with @bench or Bench.

Basic

pybench <files|directories> [options]
# alias
pyb <...>

• Directories expand to **/*bench.py.
• Colors enabled on TTY; use --no-color to disable.

Options

-k <word>             # filter by substring in case/file name
-P k=v                # override params: n, repeat, warmup, group and custom params (repeatable)
--no-color            # disable ANSI colors
--sort [group|time]   # sort groups or by avg time within group
--desc                # descending order
--budget 300ms        # per-variant budget (calibration). Accepts ns, ms, s
--max-n 1000000       # cap for calibrated n
--profile [fast|thorough|smoke]
--brief               # compact output: benchmark, time(avg), vs base

Profiles:

• fast: budget≈150ms, repeat=10
• thorough: budget≈1s, repeat=30
• smoke: no calibration, repeat=3, warmup=0

Overrides with -P

pybench examples/ -P repeat=5 -P n=10000 -P warmup=0
pybench examples/ -P group=strings
pybench examples/ -P sep=":"  # override a case parameter

Sorting and brief mode

pybench examples/ --sort time --desc
pybench examples/ --brief

Header and table

• Header: CPU, Python, clock resolution, profile/mode.
• Table: mean, iter/s, min…max, p75/p99/p995, baseline and speed vs base. “≈ same” when ≤1% diff.