pytest-xdist
Parallel and distributed testing plugin for pytest — runs tests concurrently across CPU cores or remote machines. pytest-xdist features: -n auto (use all CPU cores), -n 4 (specific worker count), looponfail mode (-f, rerun on file change), distributed mode across SSH remote workers, --dist=loadfile/loadscope/loadgroup scheduling strategies, test isolation via forked workers, and xfail/pytest.mark.xdist_group for grouping. Reduces large agent test suite runtime by 2-8x through parallelism.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Local test execution — no security concerns for typical use. SSH remote workers use SSH credentials — store in CI secrets. Parallel agent tests may expose race conditions in production code — treat discovered races as security bugs (TOCTOU vulnerabilities).
⚡ Reliability
Best When
Your agent pytest suite takes >30 seconds and tests are properly isolated — pytest-xdist's -n auto makes full suite 2-6x faster with zero code changes when tests don't share mutable state.
Avoid When
Tests share global state, require specific execution order, or your suite is already fast enough.
Use Cases
- • Agent CI speedup — pytest -n auto runs agent test suite across all CPU cores; 100-test suite: 60s sequential → 15s with -n 4; CI machines with 8 cores run agent tests 4-6x faster
- • Agent isolated test workers — pytest -n 4 --dist=loadfile distributes tests from same file to same worker; agent tests accessing shared fixtures in same file run on one worker; reduces database contention in parallel agent test runs
- • Agent load-scope distribution — pytest -n 4 --dist=loadscope distributes tests from same module to same worker; agent module-level fixtures (database setup, agent initialization) created once per module per worker
- • Agent looponfail development — pytest -f watches source files; agent tests rerun automatically on file change; development loop: edit agent code → tests rerun in <5 seconds; faster than manual pytest invocation
- • pytest.mark.xdist_group grouping — @pytest.mark.xdist_group('agent-db') ensures all marked tests run on same worker; agent tests sharing transactional fixtures grouped explicitly; eliminates data races between parallel agent test processes
Not For
- • Tests with global shared state — parallel tests accessing same global variables, singletons, or shared files cause race conditions; fix test isolation before enabling xdist
- • Tests requiring specific order — xdist distributes tests without order guarantee; for ordered test sequences use pytest-ordering and -n1
- • Very fast test suites — xdist worker startup adds 1-5 seconds overhead; for test suites completing in <10 seconds, sequential is faster
Interface
Authentication
No auth — local parallel test execution. SSH remote workers use SSH credentials.
Pricing
pytest-xdist is MIT licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Database session scope conflicts with -n > 1 — SQLAlchemy session-scoped fixtures create one DB session per module; with xdist multiple workers use same module fixture causing session conflicts; use function-scoped DB fixtures with xdist or use transaction rollback per test; agent DB tests need careful fixture scoping for parallelism
- ⚠ pytest-cov requires --cov-append with xdist — parallel workers write separate .coverage.gw0, .coverage.gw1 files; coverage combine required after parallel run; pytest-cov with xdist needs --cov-append or separate coverage combine step; agent CI coverage reports may be incomplete without proper xdist+cov setup
- ⚠ Random port fixtures conflict across workers — agent integration tests creating servers on fixed ports fail when multiple workers start servers on same port; use socket with port 0 (OS assigns) for dynamic port allocation: server_port = socket.bind(('', 0)); agent tests with fixed ports must use pytest.mark.xdist_group to serialize
- ⚠ -n auto may over-subscribe on hyperthreaded CPUs — -n auto uses os.cpu_count() which counts hyperthreads; 8-core/16-thread machine runs 16 workers but IO-bound agent tests benefit from ~8; try -n 8 explicitly for CPU-heavy agent test suites; too many workers causes memory pressure
- ⚠ Worker startup failure shows no tests run — if xdist worker fails to start (import error, fixture crash), pytest exits with 'no tests ran'; error message may be truncated in worker output; use -v or --workers-output-lines=100 to see full worker startup error; agent import errors in conftest.py crash all workers silently
- ⚠ Ordering-dependent tests become flaky with xdist — tests relying on setUp order (global cache populated by test A before test B runs) fail intermittently when xdist runs B before A; agent tests must be fully independent; use autouse fixtures for state setup instead of depending on test execution order
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for pytest-xdist.
Scores are editorial opinions as of 2026-03-06.