ModuleNotFoundError: No module named 'xdist'

TL;DR

Run python -m pip install pytest-xdist. The -n flag only exists when the xdist plugin is installed; without it, pytest does not recognize -n auto at all.

ModuleNotFoundError: No module named 'xdist'

Fix it

1. Install the plugin. Run python -m pip install pytest-xdist.

   • Expected: Successfully installed pytest-xdist-... execnet-....

2. Verify. Run pytest --version and confirm xdist appears in the plugins list.

   • Expected: plugins: xdist-3.x.x.

3. Use it. Run pytest -n auto.

   • Expected: tests distribute across workers instead of unrecognized arguments: -n.

When this applies

• pytest -n auto says unrecognized arguments, or something imports xdist directly and fails.
• A fresh environment where you installed pytest but forgot xdist.

When it does not apply

• If -n is accepted but workers crash importing your own modules, that is a PYTHONPATH issue in workers, not a missing xdist.

Tool compatibility

pytest-xdist 3.x with pytest 7/8, Python 3.8+.

Why it happens

Parallel execution is a plugin, not core pytest. The package name is pytest-xdist but the import name is xdist.

Edge cases

• In CI, make sure the test step installs the same requirements file that includes pytest-xdist.

pytest-xdist's PyPI page (https://pypi.org/project/pytest-xdist/) documents pip install pytest-xdist and notes the -n option only exists when the plugin is installed. The package/import name split (pytest-xdist vs xdist) is the standard confusion, and execnet is its documented runtime dependency.