Skip to content
PyBenchx

Getting Started

Install

Section titled “Install”
Terminal window
pip install pybenchx
# or
uv pip install pybenchx

First benchmark (function mode)

Section titled “First benchmark (function mode)”

Create examples/hello_bench.py:

from pybench import bench


@bench(name="hello", n=1_000, repeat=10)
def hello():
    return sum(range(50))

Run:

Terminal window
pybench examples/

Filter and tweak at runtime:

Terminal window
pybench examples/ -k hello -P repeat=5 -P n=10_000

Isolating the hot path (context mode)

Section titled “Isolating the hot path (context mode)”
from pybench import Bench, BenchContext


suite = Bench("math")


@suite.bench(name="baseline", baseline=True, repeat=10)
def baseline(b: BenchContext):
    setup = list(range(100))
    b.start()
    sum(setup)  # timed
    b.end()

Why: context mode excludes per-iteration setup from timing, improving signal.

Discovery and naming

Section titled “Discovery and naming”
  • Directories expand to **/*bench.py.
  • Name cases with name=. Use group= to cluster related cases.
@suite.bench(name="join-basic", group="strings")

Baseline and groups

Section titled “Baseline and groups”
  • Set baseline=True on one case per group. Others show “vs base”.
  • Without an explicit baseline, a case whose name includes “baseline/base” may be used.

Profiles you’ll use

Section titled “Profiles you’ll use”
Terminal window
pybench examples/ --profile fast      # ~150ms per variant, repeat=10
pybench examples/ --profile thorough  # ~1s per variant, repeat=30
pybench examples/ --profile smoke     # no calibration, repeat=3

Next steps

Section titled “Next steps”
  • Read CLI for options (--no-color, --sort, --budget, --max-n).
  • See API for parameterization (params={...}) and suites.
  • Explore Examples for common patterns.