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

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

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

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.

Terminal

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

Derive from the runner’s known CPUs

.github/workflows/ci.yml

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

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.