ModuleNotFoundError: No module named 'execnet'

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.