pytest "error: unrecognized arguments" - Missing Plugin in CI

pytest rejected a command-line option it does not know. The option (--cov, --asyncio-mode, -n) is provided by a plugin that is not installed in the environment running the tests.

What this error means

pytest exits early (code 4) with error: unrecognized arguments: --cov or similar. The same command works locally where the plugin is installed - the CI environment is just missing the plugin.

pytest output

ERROR: usage: pytest [options] [file_or_dir] ...
pytest: error: unrecognized arguments: --cov=src --cov-report=xml
  inifile: pyproject.toml

Common causes

The plugin providing the option is not installed

--cov comes from pytest-cov, -n from pytest-xdist, --asyncio-mode from pytest-asyncio. If the plugin is absent, pytest never registers the option.

Options pinned in config but plugin not in CI deps

An addopts = "--cov" in pyproject.toml requires the plugin every run; if CI installs a thinner dependency set, the option is unrecognized.

How to fix it

Install the plugin that provides the option

Add the plugin to the test dependencies installed in CI.

Terminal

pip install pytest-cov        # provides --cov
# or pytest-xdist (-n), pytest-asyncio (--asyncio-mode)
pytest --cov=src

Keep test deps and config in sync

List every plugin your addopts/config relies on in the test extras.
Install that exact set in CI (e.g. pip install -e ".[test]").
Pin plugin versions so the option set is stable.

How to prevent it

Declare all pytest plugins your config requires in test dependencies.
Install the test extra in CI so plugins match local.
Pin plugin versions alongside pytest.