ModuleNotFoundError: No module named 'pytest_xdist'

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Import xdist, not pytest_xdist. The package is called pytest-xdist on PyPI but the importable module is just xdist. If you actually need the plugin, pip install pytest-xdist is the fix.

ModuleNotFoundError: No module named 'pytest_xdist'

Fix it

1. Fix the import. Change import pytest_xdist to import xdist.

   • Expected: the import succeeds (if pytest-xdist is installed).

2. If it still fails, install the package: python -m pip install pytest-xdist.

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

When this applies

• You guessed the module name from the PyPI package name.
• Code or docs you copied use the wrong import.

When it does not apply

• If import xdist also fails, the package is genuinely not installed.

Tool compatibility

pytest-xdist 2.x/3.x. The module has always been xdist.

Why it happens

PyPI package names and import names often differ. The pytest- prefix is a naming convention for plugins; the module drops it.

Edge cases

• Same trap as pytest-cov (module pytest_cov, which keeps the prefix) versus pytest-xdist (module xdist, which drops it). Check each plugin's docs.

The pytest-xdist documentation and PyPI page (https://pypi.org/project/pytest-xdist/) show the package name pytest-xdist while the plugin registers under the xdist entry point and module. Guessing import pytest_xdist from the package name is the standard mistake; the correct module is xdist.

Not specified by the original author.

TL;DR

Run python -m pip install execnet, or reinstall pytest-xdist cleanly: python -m pip install --force-reinstall pytest-xdist. execnet is xdist's worker-communication dependency; a partial or --no-deps install leaves it missing.

ModuleNotFoundError: No module named 'execnet'

Fix it

1. Install the missing dependency. Run python -m pip install execnet.

   • Expected: Successfully installed execnet-....

2. Or reinstall the plugin with deps. Run python -m pip install --force-reinstall pytest-xdist.

   • Expected: both pytest-xdist and execnet installed.

3. Verify. Run pytest -n 2 --collect-only -q.

   • Expected: collection succeeds, workers spawn.

When this applies

• xdist is installed but workers fail immediately importing execnet.
• You installed with --no-deps or copied site-packages by hand.

When it does not apply

• If xdist itself is missing, install pytest-xdist first.

Tool compatibility

pytest-xdist 3.x requires execnet. Python 3.8+.

Why it happens

pip normally installs dependencies automatically, but --no-deps, --target hacks, or vendored environments can skip execnet while keeping xdist.

Edge cases

• Some minimal Docker images strip deps; add execnet explicitly to requirements.

execnet is the documented runtime dependency of pytest-xdist (listed on its PyPI page at https://pypi.org/project/pytest-xdist/), used for worker communication. Partial installs with --no-deps are the standard way this specific ModuleNotFoundError appears while xdist itself imports fine.