How to run tests in parallel with pytest-xdist

pytest-xdist distributes pytest tests across worker processes. Use it in a project with an existing test suite whose tests can run independently.

Install pytest-xdist

Add pytest-xdist as a dev dependency using uv:

uv add --dev pytest-xdist

Run tests in parallel

Pass -n auto to start one worker per physical CPU core by default:

uv run pytest -n auto

To specify an exact number of workers:

uv run pytest -n 4

Each worker runs in its own process with its own Python interpreter. Tests are distributed to workers as they become available. The output is collected and displayed as a single report.

Set parallel execution as the default

Add -n auto to your pyproject.toml so parallel execution happens without remembering the flag:

[tool.pytest.ini_options]
addopts = "-n auto"

To temporarily override this and run tests sequentially (useful for debugging):

uv run pytest -n 0

Check for shared resources

Workers have separate Python processes, but they can still collide when writing to the same file, database, or network port. Keep affected tests sequential with -n 0 until those resources are isolated.

Session-scoped fixtures run once per worker, not once for the entire run. For coordination across workers, see pytest-xdist’s shared-fixture guidance.

Control test distribution

By default, pytest-xdist distributes tests to available workers using load balancing (--dist load). It sends pending tests in chunks to whichever worker is free. The most useful alternative modes:

• --dist loadscope groups tests by module or class, keeping them on the same worker. This avoids redundant setup when tests share module- or class-scoped fixtures.
• --dist loadfile groups tests from the same file on one worker. Similar to loadscope but scoped to files only.
• --dist worksteal starts with an even split, then lets idle workers steal tests from busy ones. Good for suites with uneven test durations.

uv run pytest -n auto --dist loadscope

See the pytest-xdist distribution docs for the full list of modes.

Measure the speedup

Compare sequential and parallel run times:

uv run pytest -n 0 --durations=10     # sequential, even with -n auto in addopts
uv run pytest -n auto --durations=10  # parallel

Both commands print a test summary and the slowest test durations. If the speedup is less than expected, check for a few slow tests that dominate total time. Parallelism helps most when many tests take roughly the same amount of time.