The pytest-xdist plugin extends pytest with new test execution modes, primarily designed for distributing tests across multiple CPUs or hosts to significantly speed up test execution. It also offers features like running tests in a Python subprocess and formerly supported remote SSH execution and `--looponfail` mode. Currently at version 3.8.0, the library is actively maintained with regular feature updates and bug fixes.
pip install pytest-xdistVerified import paths — ran on the pinned version, not inferred.
After installation, `pytest-xdist` is typically used directly from the command line by adding the `-n` or `--numprocesses` option to your `pytest` command. The most common use is `pytest -n auto` to automatically detect and utilize all available physical CPU cores, or `pytest -n <NUM>` to specify a fixed number of worker processes. This example demonstrates how you would invoke it programmatically via `subprocess`, though direct command-line execution is the primary quickstart.
For debugging, run tests without `-n` (i.e., sequentially). For inspecting output, rely on logging or `--capture=fd` (file descriptor capture) where available and aggregated at the end of the run.
Ensure parameterized values have a consistent order by converting them to lists or sorting them (e.g., `list({'a', 'b'})` or `sorted({'a', 'b'})`).Migrate away from using `--looponfail` (which is already deprecated). For `--rsyncdir`, consider alternative methods for syncing code to remote environments, as modern CI/CD practices often handle this differently. The `--boxed` argument was also deprecated and removed in 3.0.0, use `pytest-forked` and `--forked` instead.
For fixtures that truly need to run once per entire test session across all workers, explicit inter-process communication or shared storage (e.g., temporary files) is required, often with a 'first worker initializes, others wait' pattern. Consider using plugins like `pytest-shared-session-scope`.
If strict `--exitfirst` behavior is critical for your workflow, you might need to pin `pytest-xdist` to version `3.3.1` or earlier. Alternatively, check the latest `pytest-xdist` documentation or issue tracker for updates or workarounds regarding this behavior.
Investigate logs for the specific tests running at the time of the timeout to identify the hanging test or process. Consider adding more granular timeouts at the test or fixture level (e.g., using `pytest-timeout`) if a specific test is the culprit. Review system resource utilization during the test run if the entire environment becomes unresponsive. Ensure external services or resources accessed by tests are stable and responsive.