pytest-xdist

Visit Website

Introduction

pytest-xdist extends pytest with distributed testing. The most common use is pytest -n auto, which starts one worker process per CPU and distributes tests among them.

Distribution modes control grouping: load sends tests to any free worker, loadscope keeps tests from the same module or class together, loadfile groups by file and loadgroup honours explicit groups. Workers can also run on remote hosts. Tests must be independent for parallel runs to be reliable, so xdist often exposes hidden shared state.

In the quality loop it shortens Python feedback time, locally and in CI.

The source code is at pytest-dev/pytest-xdist on GitHub under the MIT licence, with about 1,900 stars; the most recent commit was on 2 November 2026.

Features

1. Multi-CPU runs: -n auto uses all cores.
2. Distribution modes: load, loadscope, loadfile and loadgroup.
3. Remote workers: Distribute to other machines.
4. Plugin compatible: Works with most pytest plugins.
5. Worker IDs: Fixtures can isolate resources per worker.
6. Mature: A long-standing pytest-dev project.

Pros

1. Large speed-ups: Near-linear gains for CPU-bound suites.
2. Free to use: Open source under the MIT licence, so the core tool costs nothing to use.
3. Actively maintained: The repository had commits as recent as 2 November 2026.

Cons

1. Shared state issues: Order-dependent tests fail in parallel.
2. Output interleaving: Debugging is harder than serial runs.
3. Not cross-node balancing: Use pytest-split for CI sharding by timing.

Usage and Links (Example)

pip install pytest-xdist
pytest -n auto --dist loadscope

Resources:

• pytest-xdist website
• GitHub repository

Pricing

pytest-xdist is free and open source under the MIT licence.

Recommended for?

1. Python teams with slow test suites.
2. CI pipelines on multi-core runners.

Conclusion

pytest-xdist is the standard way to parallelise pytest.

Fix shared-state bugs it reveals rather than turning it off.

On CheckOps, pytest-xdist is filed under the Release & CI gates and Unit testing stages. Related tools listed here include pytest, pytest-split, pytest-rerunfailures, Knapsack Pro, tox and Nox. Which one fits best depends mostly on your stack, your team’s size and skills, and whether you prefer to run tools yourself or pay for a managed service. This page reflects the official website, documentation and repository as they stood on 11 November 2026.