pyperf

library2.10.0pypypi✓ verified 87d ago

pyperf is a Python module designed to write, run, and analyze benchmarks. It provides a robust API for reliable performance measurements, including automatic calibration, multi-process execution, statistical analysis with outlier detection, and comprehensive metadata collection. Currently at version 2.10.0, pyperf maintains an active release cadence with regular updates and requires Python 3.9 or newer.

testing observability

pip install pyperf

github ↗package ↗

INSTALL

IMPORT

SIG · PYPERF

pyperf

testingpythonv2.10.0

Install

1.8s avg

Import

182ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.10.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.191s · 19.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.173s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Runner

✓ from pyperf import Runner

pyperf

✓ import pyperf

✗ import perf

The library was renamed from 'perf' to 'pyperf' in version 1.6.0. Old imports will cause a ModuleNotFoundError.

This quickstart demonstrates benchmarking a simple function using `pyperf.Runner`. It shows how to define a function to be benchmarked and then execute it with the runner. The output will include mean execution time and standard deviation. For more complex scenarios, `runner.timeit()` is suitable for benchmarking single statements, and results can be saved to a JSON file using the `-o` command-line option when running the script.

import pyperf import time def my_benchmark_func(): time.sleep(0.001) runner = pyperf.Runner() # Benchmark a simple function runner.bench_func('sleep_1ms', my_benchmark_func) # Or benchmark a statement # runner.timeit( # name="sort a sorted list", # stmt="sorted(s, key=f)", # setup="f = lambda x: x; s = list(range(1000))" # ) # Results are printed to stdout by default. Use -o output.json for file output.

pyperf --version

Debug

Known issues

breakingpyperf 2.x requires Python 3.9 or newer. Python 3.8 and older are no longer supported. Attempting to use newer pyperf versions on older Python versions will result in a `RuntimeError`.

fix

Upgrade your Python environment to 3.9 or newer. For Python 2.7, use `pyperf==1.7.1`.

affects: >=2.0.0

breakingThe project was renamed from `perf` to `pyperf` in version 1.6.0. Old `import perf` statements will cause `ModuleNotFoundError`.

fix

Update all imports from `import perf` to `import pyperf` in your code.

affects: >=1.6.0

deprecated`pyperf.perf_counter()` was deprecated in version 2.0.0. It is recommended to use Python's built-in `time.perf_counter()` directly.

fix

Replace calls to `pyperf.perf_counter()` with `time.perf_counter()`.

affects: >=2.0.0

gotchaBenchmarks may report 'WARNING: the benchmark result may be unstable' due to high variance, often from system jitter or insufficient measurement runs/values. This can lead to unreliable performance figures.

fix

Rerun the benchmark with more `--runs`, `--values`, or `--loops` (e.g., `python3 your_script.py --runs 40 --values 20`). Consider running `python3 -m pyperf system tune` to prepare your system for stable benchmarking.

affects: All

gotchaMemory tracking using the `--track-memory` option requires the optional `psutil` package. If `psutil` is not installed, memory tracking will not function, particularly on macOS, and may lead to unexpected behavior or incomplete data.

fix

Install the `psutil` dependency: `pip install psutil`.

affects: All

breakingIn pyperf 2.0.0, the terminology changed from 'sample' to 'value' across the API and command-line options. For example, `Benchmark.get_samples()` became `Benchmark.get_values()`, and `--samples` became `--values`.

fix

Update your code and command-line scripts to use 'value' terminology. For instance, replace `runner.bench_sample_func()` with `runner.bench_time_func()`.

affects: >=2.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'perf'

The library was renamed from 'perf' to 'pyperf' in version 1.6.0. Your code is trying to import the old name.

fix

Update your import statements from `import perf` to `import pyperf`, and update any references to `perf` within your code.

RuntimeError: pyperf requires Python 3.9 or newer

You are attempting to run a pyperf version (>=2.0.0) that is incompatible with your current Python interpreter (e.g., Python 3.8 or older).

fix

Upgrade your Python environment to version 3.9 or higher. If you must use Python 2.7, install an older version of pyperf: `pip install pyperf==1.7.1`.

WARNING: the benchmark result may be unstable * the maximum (X us) is Y% greater than the mean (Z us)

pyperf detected a significant variance in benchmark results, indicating potential instability in measurements or insufficient data points.

fix

Increase the number of runs, values, and/or loops by passing options like `--runs N`, `--values N`, `--loops N` to your benchmark command. Running `python3 -m pyperf system tune` can also help reduce system jitter.

AttributeError: 'Runner' object has no attribute 'bench_sample_func'

In pyperf 2.0.0, the `bench_sample_func` method (and similar 'sample' terminology) was renamed to `bench_time_func` (and 'value' terminology).

fix

Update your code to use the newer method name: `runner.bench_time_func()`. Similarly, update any command-line options like `--samples` to `--values`.

Upgrade

Version history

2.10.0latest on PyPI · released Feb 7, 2026

Audit

Dependencies

psutiloptionalRequired for memory tracking features (e.g., --track-memory), especially on macOS.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/psf/pyperf ↗

packagehttps://pypi.org/project/pyperf/ ↗