NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #213 most downloaded on PyPI
pytest xdist plugin for distributed testing, most importantly across multiple CPUs
Last release 1 years ago
01 Jul 2025
Release timing varies
gaps range from 8 days to 13 months
Most releases are documented
notes for 49 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
17 years old
71 releases · first in 2010
For example, [test_file_1, test_file_2, ..., test_file_n] are given as input test files, if --no-loadscope-reorder is used, for either worker, the tes
#1083: Add --no-loadscope-reorder and --loadscope-reorder option to control whether to automatically reorder tests in loadscope for tests where relative ordering matters. This only applies when using loadscope.
For example, [test_file_1, test_file_2, ..., test_file_n] are given as input test files, if --no-loadscope-reorder is used, for either worker, the test_file_a will be executed before test_file_b only if a < b.
The default behavior is to reorder the tests to maximize the number of tests that can be executed in parallel.
This is a prerequisite for group/scope support in the worksteal scheduler, so test groups won't be broken up incorrectly.
One column per quarter.
#1142: Added support for Python 3.13.
#1144: The internal steal command is now atomic - it unschedules either all requested tests or none.
This is a prerequisite for group/scope support in the worksteal scheduler, so test groups won't be broken up incorrectly.
#1170: Add the --px arg to create proxy gateways.
Proxy gateways are passed to additional gateways using the via keyword. They can serve as a way to run multiple workers on remote machines.
#1200: Now multiple xdist_group markers are considered when assigning tests to groups (order does not matter).
Previously, only the last marker would assign a test to a group, but now if a test has multiple xdist_group marks applied (for example via parametrization or via fixtures), they are merged to make a new group.
#1162: Dropped support for EOL Python 3.8.
Bug Fixes --------- - #1071 _: Add backward compatibility for deadlock issue with the execnet new main_thread_only "execmodel" triggered when pytest-c
#1071: Add backward compatibility for deadlock issue with the execnet new main_thread_only "execmodel" triggered when pytest-cov accesses rinfo.
This release was YANKED due to a regression fixed in 3.6.1.
This release was YANKED due to a regression fixed in 3.6.1.
#1027:pytest-xdist workers now always execute the tests in the main thread. Previously some tests might end up executing in a separate thread other than main in the workers, due to some internal execnet` details. This can cause problems specially with async frameworks where the event loop is running in the main thread (for example #620).
#1024: Added proper handling of shouldstop (such as set by --max-fail) and shouldfail conditions in workers. Previously, a worker might have continued executing further tests before the controller could terminate the session.
#1028: Fixed compatibility issue between looponfail and editable installs.
#620: Use the new main_thread_only execnet "execmodel" so that code which expects to only run in the main thread will now work as expected.
#937: Fixed a bug where plugin would raise an incompatibility error with --pdb despite using -n0.
#1053: Dropped support for Python 3.7.
#1057: pytest>=7.0.0 is now required.
execnet>=2.1.0 is now required.
#1020: pytest-xdist's setup.py file is removed.
If you relied on this file, e.g. to install pytest using setup.py install, please see Why you shouldn't invoke setup.py directly for alternatives.
#1057: The internals of pytest-xdist are now fully typed. The typing is not exposed yet.
#996: Adjusted license file format and content to ensure security scanners will identity the license.
Features -------- - #632 _: --dist=loadscope now sorts scopes by number of tests to assign largest scopes early -- in many cases this should improve o
#632: --dist=loadscope now sorts scopes by number of tests to assign largest scopes early -- in many cases this should improve overall test session running time, as there is less chance of a large scope being left to be processed near the end of the session, leaving other workers idle.
This makes sure that the results of in-progress tests are displayed. Previously these reports were being discarded, losing information about the test
A more safe correction will require thread affinity in execnet (pytest-dev/execnet#96 __).
#907: Avoid remote calls during startup as execnet by default does not ensure remote affinity with the main thread and might accidentally schedule the pytest worker into a non-main thread, which breaks numerous frameworks, for example asyncio, anyio, PyQt/PySide, etc.
A more safe correction will require thread affinity in execnet (pytest-dev/execnet#96).
Features -------- - #555 _: Improved progress output when collecting nodes to be less verbose.
#555: Improved progress output when collecting nodes to be less verbose.
Bug Fixes --------- - #884 _: Fixed hang in worksteal scheduler.
#884: Fixed hang in worksteal scheduler.
Fixes #874
Fixes #874
#863: Document limitations for debugging due to standard I/O of workers not being forwarded. Also, mention remote debugging as a possible workaround.
#855: Users can now configure load scheduling precision using --maxschedchunk command line option.
#858: New worksteal scheduler, based on the idea of work stealing. It's similar to load scheduler, but it should handle tests with significantly differing duration better, and, at the same time, it should provide similar or better reuse of fixtures.
#870: Make the tests pass even when $PYTEST_XDIST_AUTO_NUM_WORKERS is set.
[pytest] addopts = --dist loadscope
The rsync feature will be removed in pytest-xdist 4.0.
#813: Cancel shutdown when a crashed worker is restarted.
#825: The --rsyncdir command line argument and rsyncdirs config variable are deprecated.
The rsync feature will be removed in pytest-xdist 4.0.
#826: The --looponfail command line argument and looponfailroots config variable are deprecated.
The loop-on-fail feature will be removed in pytest-xdist 4.0.
#791: Document the pytest_xdist_auto_num_workers hook.
#796: Added known limitations section to documentation.
#829: Document the -n logical option.
#792: The environment variable PYTEST_XDIST_AUTO_NUM_WORKERS can now be used to specify the default for -n auto and -n logical.
#812: Partially restore old initial batch distribution algorithm in LoadScheduling.
pytest orders tests for optimal sequential execution - i. e. avoiding unnecessary setup and teardown of fixtures. So executing tests in consecutive chunks is important for optimal performance.
In v1.14, initial test distribution in LoadScheduling was changed to round-robin, optimized for the corner case, when the number of tests is less than 2 * number of nodes. At the same time, it became worse for all other cases.
For example: if some tests use some "heavy" fixture, and these tests fit into the initial batch, with round-robin distribution the fixture will be created min(n_tests, n_workers) times, no matter how many other tests there are.
With the old algorithm (before v1.14), if there are enough tests not using the fixture, the fixture was created only once.
So restore the old behavior for typical cases where the number of tests is much greater than the number of workers (or, strictly speaking, when there are at least 2 tests for every node).
#468: The --boxed command-line option has been removed. If you still need this functionality, install pytest-forked separately.
Deprecations and Removals ------------------------- - #468 _: The --boxed command line argument is deprecated. Install pytest-forked __ and use --fork
#468: The --boxed command line argument is deprecated. Install pytest-forked and use --forked instead. pytest-xdist 3.0.0 will remove the --boxed argument and pytest-forked dependency.
#722: Full compatibility with pytest 7 - no deprecation warnings or use of legacy features.
#733: New --dist=loadgroup option, which ensures all tests marked with @pytest.mark.xdist_group run in the same session/worker. Other tests run distributed as in --dist=load.
#708: Use @pytest.hookspec decorator to declare hook options in newhooks.py to avoid warnings in pytest 7.0.
#719: Use up-to-date setup.cfg/pyproject.toml packaging setup.
#720: Require pytest>=6.2.0.
#721: Started using type annotations and mypy checking internally. The types are incomplete and not published.
Depends on the setproctitle __ package, which can be installed with pip install pytest-xdist[setproctitle].
#696: On Linux, the process title now changes to indicate the current worker state (running/idle).
Depends on the setproctitle package, which can be installed with pip install pytest-xdist[setproctitle].
#704: Add support for Python 3.10.
This is very useful for test suites which are not CPU-bound.
#654: Python 3.5 is no longer supported.
#646: Add --numprocesses=logical flag, which automatically uses the number of logical CPUs available, instead of physical CPUs with auto.
This is very useful for test suites which are not CPU-bound.
#650: Added new pytest_handlecrashitem hook to allow handling and rescheduling crashed items.
#421: Copy the parent process sys.path into local workers, to work around execnet's python -c adding the current directory to sys.path.
#638: Fix issue caused by changing the branch name of the pytest repository.
Bug Fixes --------- - #623 _: Gracefully handle the pending deprecation of Node.fspath by using config.rootpath for topdir.
#623: Gracefully handle the pending deprecation of Node.fspath by using config.rootpath for topdir.
Features -------- - #608 _: Internal errors in workers are now propagated to the master node.
#608: Internal errors in workers are now propagated to the master node.
pip install pytest-xdist[psutil]
#585: New pytest_xdist_auto_num_workers hook can be implemented by plugins or conftest.py files to control the number of workers when --numprocesses=auto is given in the command-line.
#585: psutil has proven to make pytest-xdist installation in certain platforms and containers problematic, so to use it for automatic number of CPUs detection users need to install the psutil extra:
pip install pytest-xdist[psutil]
Deprecations and Removals ------------------------- - #541 _: Drop backward-compatibility "slave" aliases related to worker nodes. We deliberately mov
#541: Drop backward-compatibility "slave" aliases related to worker nodes. We deliberately moved away from this terminology years ago, and it seems like the right time to finish the deprecation and removal process.
#569: pytest-xdist no longer supports Python 2.7.
#504: New functions xdist.is_xdist_worker, xdist.is_xdist_master, xdist.get_xdist_worker_id, to easily identify the current node.
#471: Fix issue with Rsync reporting in quiet mode.
#553: When using -n auto, count the number of physical CPU cores instead of logical ones.
#541: pytest-xdist now requires pytest>=6.0.
Features -------- - #549 _: Make --pdb imply --dist no, as the two options cannot really work together at the moment. Bug Fixes --------- - #478 _: Fi
#549: Make --pdb imply --dist no, as the two options cannot really work together at the moment.
Features -------- - #554 _: Fix warnings support for upcoming pytest 6.0. Trivial Changes --------------- - #548 _: SCM and CI files are no longer inc
Deprecations and Removals ------------------------- - #475 _: Drop support for EOL Python 3.4. Features -------- - #524 _: Add testrun_uid fixture. Th
#475: Drop support for EOL Python 3.4.
#524: Add testrun_uid fixture. This is a shared value that uniquely identifies a test run among all workers. This also adds a PYTEST_XDIST_TESTRUNUID environment variable that is accessible within a test as well as a command line option --testrunuid to manually set the value from outside.
Features -------- - #486 _: Add support for Python 3.8. Bug Fixes --------- - #491 _: Fix regression that caused custom plugin command-line arguments
This however only works with pytest 5.1 or later, as it required changes in pytest itself.
#448: Initialization between workers and master nodes is now more consistent, which fixes a number of long-standing issues related to startup with the -c option.
Issues:
#6: Poor interaction between -n# and -c X.cfg
#445: pytest-xdist is not reporting the same nodeid as pytest does
This however only works with pytest 5.1 or later, as it required changes in pytest itself.
#467: Fix crash issues related to running xdist with the terminal plugin disabled.
Features -------- - #226 _: --max-worker-restart now assumes a more reasonable value (4 times the number of nodes) when not given explicitly. This pre
#226: --max-worker-restart now assumes a more reasonable value (4 times the number of nodes) when not given explicitly. This prevents test suites from running forever when the suite crashes during collection.
#435: When the test session is interrupted due to running out of workers, the reason is shown in the test summary for easier viewing.
#442: Compatibility fix for upcoming pytest 5.0: session.exitstatus is now an IntEnum object.
#435: No longer show an internal error when we run out of workers due to crashes.
This also means that pytest-xdist now requires pytest>=4.4.
#426: pytest-xdist now uses the new pytest_report_to_serializable and pytest_report_from_serializable hooks from pytest 4.4 (still experimental). This will make report serialization more reliable and extensible.
This also means that pytest-xdist now requires pytest>=4.4.
Features -------- - #374 _: The new pytest_xdist_getremotemodule hook allows overriding the module run on remote nodes. - #415 _: Improve behavior of
Bug Fixes --------- - #406 _: Do not implement deprecated pytest_logwarning hook in pytest versions where it is deprecated.
#406: Do not implement deprecated pytest_logwarning hook in pytest versions where it is deprecated.
This behavior is surprising because it makes xdist runs and non-xdist runs to potentially behave differently.
#376: The current directory is no longer added sys.path for local workers, only for remote connections.
This behavior is surprising because it makes xdist runs and non-xdist runs to potentially behave differently.
#379: Warning attributes are checked to make sure they can be dumped prior to serializing the warning for submission to the master node.
This can be used via request.config.workerinput["mainargv"].
#372: Pytest versions older than 3.6 are no longer supported.
#373: Node setup information is hidden when pytest is run in quiet mode to reduce noise on many-core machines.
#388: mainargv is made available in workerinput from the host's sys.argv.
This can be used via request.config.workerinput["mainargv"].
Bug Fixes --------- - #349 _: Correctly handle warnings created with arguments that can't be serialized during the transfer from workers to master nod
#349: Correctly handle warnings created with arguments that can't be serialized during the transfer from workers to master node.
Features -------- - #337 _: New --maxprocesses command-line option that limits the maximum number of workers when using --numprocesses=auto. Bug Fixes
Bug Fixes --------- - #344 _: Fix issue where Warnings could cause pytest to fail if they do not set the args attribute correctly.
#344: Fix issue where Warnings could cause pytest to fail if they do not set the args attribute correctly.
Bug Fixes --------- - #341 _: Fix warnings transfer between workers and master node with pytest >= 3.8.
#341: Fix warnings transfer between workers and master node with pytest >= 3.8.
Features -------- - #330 _: Improve collection performance by reducing the number of events sent to master node.
#330: Improve collection performance by reducing the number of events sent to master node.
This change caused problems in some installations, and was a mistaken in the first place as we should not change version requirements in bug-fix relea
#321: Revert change that dropped support for pytest<3.4 and require six.
This change caused problems in some installations, and was a mistaken in the first place as we should not change version requirements in bug-fix releases unless they fix an actual bug.
Remove some unnecessary references to py.builtin.
Fix issue of virtualized or containerized environments not reporting the number of CPUs correctly. (#9 _)
Add backward compatibility for slaveoutput attribute to WorkerController instances. (#285 _)
Add backward compatibility for slaveoutput attribute to WorkerController instances. (#285)
Fix issue when using loadscope or loadfile where tests would fail to start if the first scope had only one test. (#257 _)
Add support for the pytest_runtest_logfinish hook which will be released in pytest 3.4. (#266 _)
Add support for the pytest_runtest_logfinish hook which will be released in pytest 3.4. (#266)
Drop support for EOL Python 2.6. (#259 _)
Drop support for EOL Python 2.6. (#259)
New --dist=loadfile option which load-distributes test to workers grouped by the file the tests live in. (#242)
Fix accidental mutation of test report during serialization causing longrepr string-ification to break. (#241)
Fix hang when all worker nodes crash and restart limit is reached (#45 _)
xdist now supports tests to log results multiple times, improving integration with plugins which require it like pytest-rerunfailures _ and flaky _. (
xdist now supports tests to log results multiple times, improving integration with plugins which require it like pytest-rerunfailures and flaky. (#206)
Fix issue where tests were being incorrectly identified if a worker crashed during the teardown stage of the test. (#124)
Fix crash when transferring internal pytest warnings from workers to the master node. (#214 _)
Fix crash when transferring internal pytest warnings from workers to the master node. (#214)
--boxed functionality has been moved to a separate plugin, pytest-forked _. This release now depends on pytest-forked and provides --boxed as a backwa
--boxed functionality has been moved to a separate plugin, pytest-forked. This release now depends on `` pytest-forked`` and provides --boxed as a backward compatibility option. (#1)
New --dist=loadscope option: sends group of related tests to the same worker. Tests are grouped by module for test functions and by class for test methods. See README.rst for more information. (#191)
Warnings are now properly transferred from workers to the master node. (#92)
Fix serialization of native tracebacks (--tb=native). (#196)
Removal of unnecessary dependency on incorrect version of py. (#105 _)
Fixed serialization of longrepr.sections during error reporting from workers. (#171 _)
pytest-xdist now requires pytest>=3.0.0.
pytest-xdist now requires pytest>=3.0.0.
Add long option --numprocesses as alternative for -n. (#168)
Fix serialization and deserialization dropping longrepr details. (#133)
Hot fix release reverting the change introduced by #124, unfortunately it broke a number of test suites so we are reversing this change while we inves
Hot fix release reverting the change introduced by #124, unfortunately it broke a number of test suites so we are reversing this change while we investigate the problem. (#157)
Introduced towncrier for CHANGELOG management. (#154)
Added HOWTORELEASE documentation. (#155)
fix #124: xdist would mark test as complete after 'call' step. As a result, xdist could identify the wrong test as failing when test crashes at teardown. To address this issue, xdist now marks test as complete at teardown.
pytest-xdist now requires pytest 2.7 or later.
Add worker_id attribute in the TestReport
new hook: pytest_xdist_make_scheduler(config, log), can return custom tests items distribution logic implementation. You can take a look at built-in LoadScheduling and EachScheduling implementations. Note that required scheduler class public API may change in next pytest-xdist versions.
new worker_id fixture, returns the id of the worker in a test or fixture. Thanks Jared Hellman for the PR.
display progress during collection only when in a terminal, similar to pytest #1397 issue. Thanks Bruno Oliveira for the PR.
fix internal error message when --maxfail is used (#62, #65). Thanks Collin RM Stocks and Bryan A. Jones for reports and Bruno Oliveira for the PR.
new hook: pytest_xdist_node_collection_finished(node, ids), called when a worker has finished collection. Thanks Omer Katz for the request and Bruno Oliveira for the PR.
fix README display on pypi
fix #22: xdist now works if the internal tmpdir plugin is disabled. Thanks Bruno Oliveira for the PR.
fix #32: xdist now works if looponfail or boxed are disabled. Thanks Bruno Oliveira for the PR.
fix a regression -n 0 now disables xdist again
extended the tox matrix with the supported py.test versions
split up the plugin into 3 plugin's to prepare the departure of boxed and looponfail.
looponfail will be a part of core and forked boxed will be replaced with a more reliable primitive based on xdist
conforming with new pytest-2.8 behavior of returning non-zero when all tests were skipped or deselected.
new "--max-slave-restart" option that can be used to control maximum number of times pytest-xdist can restart slaves due to crashes. Thanks to Anatoly Bubenkov for the report and Bruno Oliveira for the PR.
release as wheel
"-n" option now can be set to "auto" for automatic detection of number of cpus in the host system. Thanks Suloev Dmitry for the PR.
fix issue594: properly report errors when the test collection is random. Thanks Bruno Oliveira.
some internal test suite adaptation (to become forward compatible with the upcoming pytest-2.8)
fix pytest/xdist issue485 (also depends on py-1.4.22): attach stdout/stderr on --boxed processes that die.
fix pytest/xdist issue503: make sure that a node has usually two items to execute to avoid scoped fixtures to be torn down pre-maturely (fixture teardown/setup is "nextitem" sensitive). Thanks to Andreas Pelme for bug analysis and failing test.
restart crashed nodes by internally refactoring setup handling of nodes. Also includes better code documentation. Many thanks to Floris Bruynooghe for the complete PR.
add glob support for rsyncignores, add command line option to pass additional rsyncignores. Thanks Anatoly Bubenkov.
fix pytest issue382 - produce "pytest_runtest_logstart" event again in master. Thanks Aron Curzon.
fix pytest issue419 by sending/receiving indices into the test collection instead of node ids (which are not necessarily unique for functions parametrized with duplicate values)
send multiple "to test" indices in one network message to a slave and improve heuristics for sending chunks where the chunksize depends on the number of remaining tests rather than fixed numbers. This reduces the number of master -> node messages (but not the reverse direction)
changed LICENSE to MIT
fix duplicate reported test ids with --looponfailing (thanks Jeremy Thurgood)
fix pytest issue41: re-run tests on all file changes, not just randomly select ones like .py/.c.
fix pytest issue347: slaves running on top of Python3.2 will set PYTHONDONTWRITEYBTECODE to 1 to avoid import concurrency bugs.
fix pytest-issue93 - use the refined pytest-2.2.1 runtestprotocol interface to perform eager teardowns for test items.
fix incompatibilities with pytest-2.2.0 (allow multiple pytest_runtest_logreport reports for a test item)
terser collection reporting
fix issue34 - distributed testing with -p plugin now works correctly
fix race condition in looponfail mode where a concurrent file removal could cause a crash
adapt to and require pytest-2.0 changes, rsyncdirs and rsyncignore can now only be specified in [pytest] sections of ini files, see "py.test -h" for details.
major internal refactoring to match the pytest-2.0 event refactoring - perform test collection always at slave side instead of at the master - make python2/python3 bridging work, remove usage of pickling
improve initial reporting by using line-rewriting
remove all trailing whitespace from source
perform distributed testing related reporting in the plugin rather than having dist-related code in the generic py.test distribution
depend on execnet-1.0.7 which adds "env1:NAME=value" keys to gateway specification strings.
show detailed gateway setup and platform information only when "-v" or "--verbose" is specified.
fix --looponfailing - it would not actually run against the fully changed source tree when initial conftest files load application state.
adapt for py-1.3.1's new --maxfailure option
fix issue79: sessionfinish/teardown hooks are now called systematically on the slave side
introduce a new data input/output mechanism to allow the master side to send and receive data from a slave.
fix race condition in underlying pickling/unpickling handling
use and require new register hooks facility of py.test>=1.3.0
require improved execnet>=1.0.6 because of various race conditions that can arise in xdist testing modes.
fix some python3 related pickling related race conditions
fix PyPI description
fix an indefinite hang which would wait for events although no events are pending - this happened if items arrive very quickly while the "reschedule-event" tried unconditionally avoiding a busy-loop and not schedule new work.
moved code out of py-1.1.1 into its own plugin
use a new, faster and more sensible model to do load-balancing of tests - now no magic "MAXITEMSPERHOST" is needed and load-testing works effectively even with very few tests.
cleaned up termination handling
make -x cause hard killing of test nodes to decrease wait time until the traceback shows up on first failure
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →