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

> Fix pytest-xdist "-n auto" resolving to 0 workers in CI - a container reporting 1 CPU, or all collection happening on a gateway, leaving tests not distributed.

Source: https://latchkey.dev/learn/python/pytest-xdist-n-auto-zero-workers  
Updated: 2026-06-25

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

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

```Terminal
# 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)"
```

> Exit code 5 means zero tests were collected. It is a configuration result, not a passing run, and CI that only checks for a non-zero exit will treat it as success unless you assert on the collected count.

## Make a zero-test run fail the build

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

## FAQ

### What causes pytest-xdist "-n auto" spawns zero workers / "no tests ran" in CI?

There are 2 common causes: container reports a single cpu and logical vs physical core detection. auto uses the visible CPU count.

### How do I fix pytest-xdist "-n auto" spawns zero workers / "no tests ran" in CI?

There are 2 fixes depending on which cause you have: set an explicit worker count and derive from the runner’s known cpus. Work through them in order, since the first is the most common.

### What does pytest-xdist "-n auto" spawns zero workers / "no tests ran" in CI actually mean?

A -n auto run shows 0 workers / 1 worker, runs serially despite expecting parallelism, or reports collection on the controller only.

### How do I stop pytest-xdist "-n auto" spawns zero workers / "no tests ran" in CI happening again?

Pin -n explicitly in constrained containers rather than auto. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt