Install & Compatibility
Where this runs
tested against v5.0.3 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.412s · 35.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.386s · 41MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pytest.mark.benchmark
✓ import pytest
@pytest.mark.benchmark
def test_my_function(): ...
Used as a decorator to mark an entire test function for benchmarking.
benchmark fixture
✓ def test_my_function(benchmark):
result = benchmark(lambda: my_code_to_measure())
assert result is not None
The `benchmark` fixture is automatically provided by pytest-codspeed for fine-grained control over which parts of a test function are measured.
This example demonstrates two common ways to create benchmarks with pytest-codspeed: using the `@pytest.mark.benchmark` decorator to measure an entire test function, and using the `benchmark` fixture for precise control over the code block to be measured within a test. Benchmarks can be run locally using `pytest --codspeed`.
import pytest
def sum_squares(arr):
"""Sum the squares of the numbers in an array."""
total = 0
for x in arr:
total += x * x
return total
@pytest.mark.benchmark
def test_sum_squares_full_function():
"""Benchmark an entire test function using the decorator."""
# This entire function's execution will be measured
assert sum_squares(range(1000)) == 332833500
def mean(data):
return sum(data) / len(data)
def test_mean_performance_fine_grained(benchmark):
"""Benchmark a specific part of a test function using the fixture."""
data = list(range(1_000_000)) # Setup not measured
# Only the lambda function's execution will be measured
result = benchmark(lambda: mean(data))
assert result == 499999.5
# To run locally: pytest your_test_file.py --codspeed
Debug
Known issues
breakingUpgrading to v4.0.0 introduced `CodSpeedHQ/instrument-hooks`. This may cause slight performance changes in tiny microbenchmarks compared to previous versions due to changes in how instrument states are controlled.fixReview existing benchmarks after upgrading and adjust any baselines if slight performance shifts are observed, particularly for very small, fast functions.
affects: >=4.0.0
gotchaRunning benchmarks locally with the `--codspeed` flag will display results in the console but will *not* produce performance reports or integrate with the CodSpeed dashboard. For full performance reporting, regression tracking, and consistent measurements, benchmarks must be run in a CI/CD environment using the official CodSpeed runner (e.g., GitHub Action).fixIntegrate CodSpeedHQ/action into your CI/CD workflow to enable performance reporting and historical tracking. Local runs are primarily for functional verification of benchmarks.
affects: All
gotchaWhen using the `walltime` instrument (enabled via `--codspeed-mode walltime`), avoid running multiple benchmark processes in parallel (e.g., with `pytest-xdist`). Parallel execution can lead to noisy and inconsistent measurements. For optimal consistency in walltime mode, use isolated machines like CodSpeed Hosted Macro Runners.fixConfigure your CI environment to run benchmarks in a single process when using `walltime` mode, or use CodSpeed's dedicated macro runners if available.
affects: All versions with walltime instrument (>=3.0.0)
gotchaPython 3.9 or newer is required. Older Python versions are not supported.fixEnsure your project's Python environment is 3.9 or later. Upgrade Python if necessary.
affects: <3.9
gotchaBenchmarks are still tests: always include assertions in your benchmark functions to verify that the code being measured is producing the expected output. This ensures that you're not just measuring speed, but the speed of correct functionality.fixAdd `assert` statements to your benchmark functions to validate their behavior, just like any other unit test.
affects: All
Errors
Common errors & fixes
CodSpeed Error: CODSPEED_TOKEN is not set.
The CODSPEED_TOKEN environment variable is required to authenticate with CodSpeed services and upload benchmark results, especially in CI/CD environments.
fixSet the `CODSPEED_TOKEN` environment variable in your shell or CI/CD pipeline configuration.
No benchmarks found
Pytest-codspeed did not find any test functions marked for benchmarking, so it reported zero collected benchmark tests.
fixDecorate the test functions you intend to benchmark with `@pytest.mark.codspeed`.
ModuleNotFoundError: No module named 'pytest_codspeed'
The `pytest-codspeed` package is not installed in your current Python environment or there's a typo in an explicit (though usually unnecessary for usage) import.
fixInstall the library using `pip install pytest-codspeed`.
AttributeError: 'CodspeedFixture' object has no attribute 'start'
The `codspeed` fixture does not have `start()` or `stop()` methods; users often expect this behavior from other benchmarking libraries like `pytest-benchmark`.
fixUse `with codspeed.track('section_name'):` to measure specific blocks of code within a test function. Upgrade
Version history
5.0.3latest on PyPI · released May 22, 2026
Audit
Dependencies
pytestrequiredAs a pytest plugin, it requires pytest to function.