pytest-rs

pytest-rs is a re-implementation of the popular Python testing framework pytest in Rust, focused on speed: a drop-in compatible runner where startup, collection, fixture orchestration, coverage measurement, and reporting are native code, while test bodies run on embedded CPython.

Note: This project is currently in active development (alpha stage). Many features are still under implementation and subject to change. See docs/DESIGN.md for the architecture and roadmap.

pytest-rs is an independent project, not affiliated with or endorsed by the pytest project.

Installation

Prebuilt wheels are published to PyPI for Linux (x86_64 / aarch64) and macOS (arm64) on CPython 3.13 / 3.14:

uv add --dev pytest-rs    # or: pip install pytest-rs

Then run your existing suite, no changes needed:

pytest-rs                       # whole suite, like `pytest`
pytest-rs tests/test_foo.py     # one file
pytest-rs -n 4                  # parallel workers (pytest-xdist compatible)
pytest-rs --cov=mypkg           # native coverage (pytest-cov compatible)

pytest-rs reads the same configuration pytest does (pytest.ini, pyproject.toml [tool.pytest] / [tool.pytest.ini_options], tox.ini, setup.cfg) and understands the familiar flags (-v, -x, -k, -m, --lf, --tb=..., -p no:NAME, ...). It leaves the pytest command itself untouched, but it does install an importable pytest package, so import pytest (fixtures, pytest.raises, pytest.mark, pytest.approx, ...) works standalone too — e.g. from a subprocess that never runs through the pytest-rs binary.

Don't install this alongside the real pytest package in the same environment: both distributions claim the same pytest import path, and pip/uv have no awareness that they conflict — installation order decides which files end up in site-packages/pytest/, and neither installer cleanly removes the other's.

When switching a project over, pytest itself, pluggy, and iniconfig are the only packages pytest-rs supersedes — safe to drop. Any other pytest plugin the project uses (pytest-django, pytest-aiohttp, ...) is a real, separately-installed package unless it's one of the plugins listed under Bundled plugins below, and must stay installed for its fixtures/hooks to keep working.

Watch for pytest arriving transitively: every pytest plugin declares a dependency on it, so keeping one of the bundled plugins installed (pytest-mock for its MockerFixture annotation, say) pulls the real pytest back in behind your back. uv tree --package pytest / pip show pytest after a lock change is the quick check; the annotations those plugins are usually kept around for ship with pytest-rs itself (see Type annotations).

Adding a third-party plugin without pulling pytest back in

Because every plugin depends on pytest, the obvious uv add --dev pytest-aiohttp installs the real distribution on top of pytest-rs's files. Install the plugin without its dependencies instead — the ones pytest-rs supersedes are already in place — and add back only the dependencies it genuinely needs.

Take pytest-aiohttp==1.1.1. It requires pytest, pytest-asyncio, and aiohttp: the first two are provided by pytest-rs, the third is a real package you still need.

One-off (a CI step, or trying a plugin out):

uv pip install --no-deps pytest-aiohttp==1.1.1   # or: pip install --no-deps ...
uv pip install aiohttp                           # its non-pytest dependencies, explicitly

For a locked project, keep the plugin in your dependency groups and override the requirements pytest-rs supersedes with a marker that never matches — uv then resolves the plugin but installs neither pytest nor pytest-asyncio:

[dependency-groups]
dev = ["pytest-rs", "pytest-aiohttp==1.1.1"]

[tool.uv]
override-dependencies = [
    "pytest ; sys_platform == 'never'",
    "pytest-asyncio ; sys_platform == 'never'",
]

uv sync on that project installs pytest-rs, pytest-aiohttp, and aiohttp (plus aiohttp's own deps) — and no pytest. Confirm with uv pip list | grep -i pytest: seeing a bare pytest line means the real distribution got in and has overwritten part of pytest-rs's pytest/ directory.

Which names to override is just "whichever of pytest-rs's own bundled distributions the plugin asks for": pytest, pluggy, iniconfig, plus any of the bundled plugins — e.g. a plugin depending on pytest-asyncio (pytest-aiohttp) or on pytest-xdist (pytest-split-style plugins) needs that name overridden too. Everything else the plugin depends on is a normal package: leave it alone.

Requirements

• Linux or macOS (no Windows support yet)
• CPython 3.13+ built with a shared libpython — true for uv-managed Pythons, python.org installers, Homebrew, conda, and distro packages. Plain pyenv builds need PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install ....

Bundled plugins

The compatibility layers for pytest-asyncio, anyio's pytest plugin, pytest-mock, pytest-cov, pytest-split, pytest-benchmark and pytest-xdist-style -n parallelism are built in — no separate plugin installs (the anyio layer runs tests through the installed anyio library's backends, so anyio itself must be in the environment as usual). Two ways to turn features off:

Per project or per run, like pytest (works with the prebuilt wheel):

[tool.pytest.ini_options]
addopts = "-p no:benchmark -p no:split"

At build time, when installing from source — bundled plugins are Cargo features, all enabled by default:

[tool.uv]
config-settings-package = { pytest-rs = { build-args = "--no-default-features --features asyncio,mock" } }

Type annotations

A suite that annotates its fixture parameters keeps working: the wheel installs pytest_mock, pytest_asyncio, pytest_cov and pytest_benchmark as real, py.typed packages, so

from pytest_benchmark.fixture import BenchmarkFixture
from pytest_mock import MockerFixture

def test_x(mocker: MockerFixture, benchmark: BenchmarkFixture) -> None: ...

type-checks and imports without the corresponding distributions installed — which is what keeps the real pytest out of the environment (see the note above). Each declares the surface pytest-rs's own fixture provides; where a bundled plugin is narrower than upstream, the missing attribute is left undeclared rather than typed and broken, so a type checker tells you before a run does.

pytest-split has no importable API to mirror (--splits/--group are CLI-only), and the anyio layer uses the installed anyio package's own types.

Third-party plugins (not reimplemented, loaded as-is)

Installed pytest11 entry points load through the pytest API shim — plugins pytest-rs does not reimplement can still work as-is. The supported surface includes fixtures, markers, pytest_addoption (plugin --flags and ini options), config.stash, custom hookspecs (pytest_addhooks), pytest_runtest_protocol/pytest_runtest_call hookwrappers, custom collectors (pytest_collect_file → File/Item), and terminal-reporter replacement (a plugin that unregisters the terminalreporter plugin and registers its own subclass takes over the output — pytest-rs suppresses its native rendering and drives the replacement through the same hooks pluggy would). Verified status:

A plugin that fails to import (e.g. it reaches into pytest/pluggy internals the shim doesn't provide) warns and is skipped without breaking the run. -p no:NAME and PYTEST_DISABLE_PLUGIN_AUTOLOAD opt out, like pytest.

Installing one of these into a pytest-rs environment needs care, since the plugin's own pytest dependency would reinstall the real distribution — see Adding a third-party plugin without pulling pytest back in.

Performance

Startup, collection, fixture orchestration, coverage measurement, and parallel workers are native Rust code. The main wins:

• --cov runs — coverage is collected via sys.monitoring (Python 3.12+ low-overhead instrumentation) instead of coverage.py's tracing hooks. Typically 2–3x faster, and the gap widens with suite size.
• -n parallel runs — workers fork off the already-warm parent interpreter by default (unix only), skipping per-worker interpreter/plugin/conftest import cost. Each forked worker still fires its own pytest_configure and collects/applies pytest_collection_modifyitems independently, so behavior matches a freshly spawned worker. Set PYTEST_RS_DIST_SPAWN=1 to opt back into spawning a fresh subprocess per worker (upstream xdist's model) instead.
• Large collections — fixture resolution and parametrize expansion run in Rust; suites with thousands of tests see faster collection.

Benchmarks on open-source projects (macOS arm64, median of 3 warm runs), reproducible with bench/suites.sh — clones each suite at a pinned tag, installs pytest-rs into its venv, and times both runners.

Small-to-medium suites see a 1.3–1.4x speedup even without coverage, thanks to lower startup overhead. On large suites where test bodies dominate, the plain-mode gap narrows; the bigger wins come from --cov and -n parallelism. Try it on your own suite:

hyperfine -w 1 'pytest -q' 'pytest-rs -q'
hyperfine -w 1 'pytest --cov=mypkg' 'pytest-rs --cov=mypkg'

Known limitations

• unix only (no Windows)
• no --pdb / debugger integration yet
• third-party pytest plugins are loaded via the pytest11 entry point and the pytest API shim; plugins reaching deep into pytest internals may not work (see "Third-party plugins" above for verified examples)

Conformance testing

Compatibility is verified by running the upstream test suites of the libraries pytest-rs reproduces, unchanged, under pytest-rs (conformance/).

Current results (total = passed + failed + errors + skipped + deselected + known_failed; deselected = tests that never run, excluded via --deselect in conformance/suites.toml because running them would be flaky or environmentally invalid; known_failed = tests that run normally but fail for a known, permanent, accepted reason (matched by exact nodeid against the run's own output, so a test that starts passing again is simply counted as passed instead of masking a real fix); both count against the total but not toward conformance; files excluded = whole files that also fail under vanilla pytest, out of scope; updated automatically by conformance/runner.py — see conformance/RESULTS.md for per-file detail):

linux (CI-verified)

pytest & plugin ecosystem (the APIs pytest-rs reimplements):

Third-party plugins (not reimplemented — their own upstream test suites run under pytest-rs, loaded via the pytest11 entry-point shim):

Real-world projects (their suites run unchanged, as drop-in evidence):

The suites are included as shallow git submodules under conformance/suites/ at the pinned release tags. Initialize them once after cloning:

git submodule update --init --depth 1

Then run the full conformance harness:

cargo build
uv run --no-project python conformance/runner.py --local   # uses submodules
uv run --no-project python conformance/runner.py           # re-clones from upstream (CI mode)

pytest-rs reimplements the public APIs of these projects, plus anyio's pytest plugin (MIT). Parts of the bundled Python shims are ports of upstream code; see THIRD-PARTY-NOTICES.md. Credit for the API design and the test suites belongs to their respective authors.

License

This project is licensed under the MIT License. See the LICENSE file for more details.