pytest-xdist "worker crashed" in CI

By Daniel Zoghalchali·Latchkey

A pytest-xdist worker process died mid-run - usually killed by the OS for memory, or crashed by a native extension/segfault. xdist reports the worker and the test it was running when it crashed.

What this error means

pytest-xdist reports "[gw0] node down: Not properly terminated" or "worker 'gw0' crashed while running '<test>'", and the run aborts or replays the test.

[gw1] node down: Not properly terminated
replacing crashed worker gw1
worker 'gw1' crashed while running 'tests/test_heavy.py::test_big_matrix'

Common causes

Out-of-memory under parallelism

Running many workers multiplies memory; a heavy test pushes a worker past the runner's RAM and the OS kills it.

A native crash or segfault in a worker

A C-extension fault, a hung subprocess, or a shared-state bug terminates the worker abnormally.

How to fix it

Reduce parallelism or isolate the test

1. Lower the worker count so memory per worker is sufficient.
2. Isolate or serialize the heavy/crashing test.
3. Re-run to confirm the worker no longer dies.

pytest -n 2 --dist loadscope

Right-size the runner for the workload

Give the job a larger runner so concurrent workers have enough memory.

runs-on: ubuntu-latest-8-cores

How to prevent it

• Match worker count to the runner's memory budget.
• Quarantine tests that segfault native extensions.
• Use --dist loadscope to keep related tests on one worker.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation