pytest "ImportError while importing test module" in CI

By Kaveh Alemi·Latchkey

pytest tried to import a test module during collection and the import itself raised. The hint points at duplicate filenames, a missing __init__.py, or a dependency the test imports that is not installed.

What this error means

pytest reports "ERROR collecting tests/test_x.py - ImportError while importing test module" followed by the underlying import error and a hint about test module names.

ImportError while importing test module '/home/runner/work/app/tests/test_api.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
tests/test_api.py:2: in <module>
    import requests
E   ModuleNotFoundError: No module named 'requests'

Diagnose it: what did pytest actually collect?

Most pytest failures that only happen in CI are collection or import-path problems rather than test failures. The runner has a different working directory, a different sys.path, and usually no editable install, so a test module that imports your package locally may not resolve at all.

# what would run, without running it
pytest --collect-only -q | tail -20

# where pytest thinks the root is (drives conftest and import mode)
pytest --collect-only 2>&1 | grep -i rootdir

# is the package importable at all from the runner cwd?
python -c "import yourpackage, sys; print(yourpackage.__file__)"
python -c "import sys; print(sys.path)"

Common causes

A dependency the test imports is missing

The test file imports a package not installed in the CI environment, so its import fails at collection.

Duplicate test filenames without packages

Two test_x.py files in different folders with no __init__.py collide under the default import mode.

How to fix it

Install the missing dependency

Ensure test dependencies are installed before pytest runs.

pip install -r requirements-dev.txt
pytest

Disambiguate duplicate test modules

Add __init__.py files or switch to importlib import mode so same-named files do not collide.

[pytest]
addopts = --import-mode=importlib

Make a zero-test run fail the build

# fail explicitly when nothing is collected
pytest --strict-markers -q
test "${PIPESTATUS[0]}" -ne 5 || { echo "pytest collected no tests"; exit 1; }

How to prevent it

• Install all test dependencies (a dev requirements set) in CI.
• Use unique test filenames or package the test tree with __init__.py.
• Consider --import-mode=importlib to avoid name collisions.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation