pytest ImportError: Error importing plugin (tested)

ImportError: Error importing plugin "x": No module named 'x' means a plugin named with -p, in addopts, or in pytest_plugins cannot be imported by the Python running pytest. Use the module name (pytest_mock, not pytest-mock) and install it in that environment.

pytest loads plugins from three places: -p name on the command line (or in addopts), pytest_plugins = [...] in a conftest.py, and installed packages that register themselves automatically. A plugin that cannot be imported stops pytest before collection with a Python traceback ending in ImportError: Error importing plugin. Measured on pytest 9.1.1.

1. -p with a module that is not installed

$ pytest -q -p nosuch 2>&1 | tail -1; echo "exit code: ${PIPESTATUS[0]}"
ImportError: Error importing plugin "nosuch": No module named 'nosuch'
exit code: 1

Note the exit code is 1 (an uncaught Python exception), not pytest's usage error 4. The fix is to install the plugin in the interpreter that runs pytest, or to remove the -p option (check addopts in your config).

2. -p takes the import name, not the pip name

$ pytest -q -p pytest-mock 2>&1 | tail -1
ImportError: Error importing plugin "pytest-mock": No module named 'pytest-mock'
$ pytest -q -p pytest_mock | tail -1
1 passed in 0.00s

The package pytest-mock is imported as pytest_mock. Use underscores (the module name) with -p and in pytest_plugins.

3. pytest_plugins pointing at your own module

$ cat conftest.py
pytest_plugins = ["myplugins.fixtures"]
$ pytest -q 2>&1 | tail -1; echo "exit code: ${PIPESTATUS[0]}"
ImportError: Error importing plugin "myplugins.fixtures": No module named 'myplugins'
exit code: 1

The module in pytest_plugins must be importable. A local package works when it sits next to the root conftest.py (pytest puts that directory on sys.path in the default import mode) and has an __init__.py:

$ find . -name "*.py" -not -path "*/__pycache__/*" | sort
./conftest.py
./myplugins/fixtures.py
./myplugins/__init__.py
./test_ok.py
./test_user.py
$ cat myplugins/fixtures.py
import pytest

@pytest.fixture
def user():
    return "bob"
$ pytest -q | tail -1
2 passed in 0.01s

With a src layout, add pythonpath = ["src"] to the pytest config or install the project with pip install -e . (see pytest error collecting ModuleNotFoundError).

4. "Defining pytest_plugins in a non-top-level conftest is no longer supported"

$ cat tests/sub/conftest.py
pytest_plugins = ["pytest_mock"]
$ pytest -q 2>&1 | grep -E "^ERROR|^Defining"; echo "exit code: ${PIPESTATUS[0]}"
Defining 'pytest_plugins' in a non-top-level conftest is no longer supported:
ERROR tests/sub - Failed: Defining 'pytest_plugins' in a non-top-level confte...
exit code: 2

pytest_plugins is only allowed in the conftest.py at the root of the test run. Move the line up:

$ find . -name "*.py" -not -path "*/__pycache__/*" | sort
./conftest.py
./tests/sub/test_s.py
$ pytest -q | tail -1
1 passed in 0.00s

5. "Missing required plugins" (exit code 4)

$ cat pytest.ini
[pytest]
required_plugins = pytest-django>=4.0 pytest-mock
$ pytest -q 2>&1 | head -1; echo "exit code: ${PIPESTATUS[0]}"
ERROR: Missing required plugins: pytest-django>=4.0
exit code: 4

required_plugins makes the missing plugin explicit instead of failing later with fixture not found; it lists only the ones not installed (pytest-mock was installed here). Install them in the same environment: python -m pip install "pytest-django>=4.0".

6. A broken installed plugin: see and disable autoloaded plugins

$ pytest -VV 2>&1 | grep -A1 registered
registered third-party plugins:
  pytest-mock-3.17.0 at /tmp/fx384/ve/lib/python3.13/site-packages/pytest_mock/__init__.py
$ PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -VV 2>&1 | grep -c registered
0

pytest -VV lists every auto-registered third-party plugin and where it lives. If one of them crashes on import or at startup, PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 turns autoloading off (then enable the ones you need with -p), or disable just one with -p no:<name>; upgrading or uninstalling the broken plugin is the lasting fix.

Related: pytest exit codes, pytest using the wrong Python.

Written with AI assistance. Measured on 2026-10-23 with pytest 9.1.1 (pytest-mock 3.17.0) on Python 3.13.5 in a clean virtualenv. Each block was run verbatim and the output pasted unedited. PlainHeaders is our extension; Python and pytest are free.