pytest -x and --maxfail: Fail-Fast Command Reference

Stop the run early once tests start failing.

pytest -x stops after the first failure and --maxfail=N stops after N. In CI they cut wasted minutes when a build is clearly broken, returning a red signal sooner.

Common flags / usage

-x, --exitfirst -- stop on the first failure or error
--maxfail=N -- stop after N failures/errors
combine with -q -- compact fail-fast output
pair with --ff (--failed-first) -- run last-failed tests first

Example

shell

# Bail after 3 failures to save runner minutes on a broken build:
- run: python -m pytest --maxfail=3 -q

In CI

Fail-fast trades full coverage of a run for faster feedback. Use --maxfail=N (not -x) when you still want to see a handful of failures clustered together rather than just the very first one.

Key takeaways

-x stops on the first failure; --maxfail=N stops after N.
Fail-fast saves runner minutes when a build is clearly broken.
--maxfail=N surfaces a few failures together for quicker diagnosis.

Related guides

pytest: Run Tests Command Reference for CIReference for pytest in CI: running the suite, useful flags, why python -m pytest fixes import errors, and a… pytest -n (xdist): Parallel Tests Command ReferenceReference for pytest -n from pytest-xdist in CI: running tests in parallel across CPUs with -n auto, distribu… pytest -k: Select Tests by Name Command ReferenceReference for pytest -k in CI: selecting tests by a name expression with and/or/not operators, sharding a sui…