pytest-xdist "-n auto" Spawns Zero Workers / "no tests ran" in CI

By Kaveh Alemi·Latchkey

-n auto sizes the worker pool from detected CPUs. In a constrained container that reports a single core (or with cgroup limits), auto can resolve to one - or zero useful - workers, so the distributed run behaves oddly or skips parallelism entirely.

What this error means

A -n auto run shows 0 workers / 1 worker, runs serially despite expecting parallelism, or reports collection on the controller only. On constrained CI containers the CPU count auto reads does not match the host.

$ pytest -n auto
created: 1/1 worker
1 worker [124 items]
# expected many workers on a multi-core runner

Diagnose it: what did pytest actually collect?

Most pytest failures that only happen in CI are collection or import-path problems rather than test failures. The runner has a different working directory, a different sys.path, and usually no editable install, so a test module that imports your package locally may not resolve at all.

# what would run, without running it
pytest --collect-only -q | tail -20

# where pytest thinks the root is (drives conftest and import mode)
pytest --collect-only 2>&1 | grep -i rootdir

# is the package importable at all from the runner cwd?
python -c "import yourpackage, sys; print(yourpackage.__file__)"
python -c "import sys; print(sys.path)"

Common causes

Container reports a single CPU

auto uses the visible CPU count. A container with cgroup CPU limits or a 1-vCPU runner reports few cores, so auto provisions few workers.

logical vs physical core detection

xdist may count physical cores; on hosts where that reads as 1, auto underprovisions even though more logical CPUs exist.

How to fix it

Set an explicit worker count

Pin -n to a sensible number for the runner instead of trusting detection.

pytest -n 4              # explicit
pytest -n logical        # use logical cores (xdist)

Derive from the runner’s known CPUs

- run: pytest -n "$(nproc)"

Make a zero-test run fail the build

# fail explicitly when nothing is collected
pytest --strict-markers -q
test "${PIPESTATUS[0]}" -ne 5 || { echo "pytest collected no tests"; exit 1; }

How to prevent it

• Pin -n explicitly in constrained containers rather than auto.
• Use -n logical or $(nproc) when you want CPU-derived sizing.
• Verify the worker count printed at session start matches expectations.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation