pytest Exit Code 4 "usage error" - Fix Bad Options & Config in CI

Exit code 4 means pytest rejected the invocation itself - an unrecognized option, an argument typo, or an addopts line referencing a plugin that is not installed. No tests run because pytest never got past parsing.

What this error means

pytest fails fast with ERROR: usage: and unrecognized arguments, or "no such option," and the step exits 4. It is distinct from exit 1 (test failures) and exit 5 (no tests collected) - this is a command-line/config problem.

pytest output

ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: --cov=app
  inifile: /repo/pyproject.toml
  rootdir: /repo

Common causes

A plugin-provided option without the plugin

Options like --cov (pytest-cov) or -n (pytest-xdist) only exist when the plugin is installed. In CI without it, pytest reports the flag as unrecognized.

A typo or stale option in addopts

A misspelled flag, or an addopts entry in pyproject.toml/pytest.ini referencing a removed option, makes every invocation a usage error.

How to fix it

Install the plugin that provides the option

Terminal

pip install pytest-cov pytest-xdist
pytest --cov=app -n auto

Fix the option or addopts

Run pytest -h to confirm the option exists with that exact spelling.
Check addopts in your config for stale or misspelled flags.
Remove options whose plugins you do not install in CI.

How to prevent it

Declare pytest plugins (cov, xdist) in test dependencies and install them in CI.
Keep addopts in sync with installed plugins.
Validate the pytest command with -h after changing options.