Pytest: error: unrecognized arguments (tested)

pytest: error: unrecognized arguments: --foo means pytest's own argument parser doesn't recognize that flag at all — which happens for two unrelated reasons that look identical on screen. We reproduced both on pytest 9.1.1 and measured what tells them apart.

1. The exact error, from a flag that needs a plugin

We ran a coverage flag without pytest-cov installed:

$ pytest --cov=foo
ERROR: usage: pytest [options] [file_or_dir] [file_or_dir] [...]
pytest: error: unrecognized arguments: --cov=foo
  inifile: None
  rootdir: /tmp/pytest-repro

We measured the exit code directly: 4 — pytest's dedicated "usage error" code (distinct from 1 for test failures, 2 for a user interrupt, 3 for an internal error, and 5 for no tests collected).

2. A genuine typo produces the byte-for-byte same message

We ran a deliberately misspelled real flag (--verbos instead of --verbose) and a plugin flag with no plugin at all installed (-n 2, which belongs to pytest-xdist):

$ pytest --verbos
pytest: error: unrecognized arguments: --verbos

$ pytest -n 2
pytest: error: unrecognized arguments: -n

Why this matters: both cases — a typo in a flag that was never real, and a correctly-spelled flag that belongs to a plugin you haven't installed — produce the exact same wording and exit code. Pytest's parser has no concept of "this looks like a plugin flag"; it only knows the flags currently registered by whatever plugins are actually loaded, so an unloaded plugin's flags are indistinguishable from flags that never existed.

3. The fix: install the plugin, or correct the typo

We confirmed installing the matching plugin resolves it with no other change:

$ pip install pytest-cov
$ pytest --cov=foo
...
1 passed in 0.03s

If the flag was a genuine typo, the only fix is spelling it correctly — there's no plugin to install. Since the error alone can't tell you which situation you're in, check two things before assuming either: (1) is this exact flag spelled correctly in pytest's own --help output, and (2) does a plugin you recognize (pytest-cov for --cov, pytest-xdist for -n, pytest-django for --ds, etc.) provide it. Searching the flag name plus "pytest plugin" is usually faster than guessing.

Frequently asked questions

What does pytest's 'unrecognized arguments' error mean?

pytest's own argument parser doesn't recognize that flag among any currently loaded plugins. We measured this happens identically whether the flag is a genuine typo or a real plugin flag whose plugin simply isn't installed — both give the same message and exit code 4.

How do I know if a flag needs a plugin or is just misspelled?

The error text doesn't say — we confirmed both cases are byte-for-byte identical. Check pytest --help for the exact flag spelling first, then search for which plugin (if any) provides it: --cov needs pytest-cov, -n needs pytest-xdist, --ds needs pytest-django, and so on.

What exit code does this error produce?

We measured exit code 4 in every case — pytest's dedicated usage-error code, distinct from 1 (test failures), 2 (user interrupt), 3 (internal error), and 5 (no tests collected).

Does installing the plugin fix it with no other changes needed?

Yes — we confirmed installing pytest-cov and rerunning the exact same --cov=foo command that previously errored ran cleanly (1 passed), with no config changes beyond the plugin install.

Written with AI assistance. Measured on 2026-10-03 with pytest 9.1.1 on Python 3.13.5, passing a flag that belongs to an uninstalled plugin, a genuinely misspelled flag, and the same flag again after installing the plugin. Every message and exit code below is copy-pasted output, not paraphrased. PlainHeaders is our extension; pytest is free.