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-....

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

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

1. 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.