mypy "Cannot find implementation or library stub" in CI
By Daniel Zoghalchali·Latchkey
mypy needs either the module source or a type stub to analyze an import. When it can find neither - because the package is not installed for mypy, or it ships no stubs - it reports this error.
What this error means
mypy fails with "error: Cannot find implementation or library stub for module named 'X' [import-not-found]" and a hint to install the package or stubs.
python
app/client.py:3: error: Cannot find implementation or library stub for module
named "requests" [import-not-found]
app/client.py:3: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
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.
Terminal
# 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
The package is not installed in the mypy environment
mypy resolves imports against the environment it runs in; if the dependency is missing there, it cannot find the module.
No bundled stubs and the stub package is absent
A package without inline types needs a separate types-* stub package that has not been installed.
How to fix it
Install the package and its stubs for mypy
Install the runtime package in the same environment mypy uses.
Add the types-* stub package if the library ships no inline types.
Re-run mypy.
Terminal
pip install requests types-requests
mypy app/
Let mypy install missing stubs
Use mypy's install-types to fetch known stub packages automatically.
Terminal
mypy --install-types --non-interactive app/
Make a zero-test run fail the build
Terminal
# 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 your full dependency set in the mypy CI environment.
Add the relevant types-* packages for untyped libraries.
Run mypy in the same environment that has the project dependencies.
Frequently asked questions
What causes mypy "Cannot find implementation or library stub" in CI?
There are 2 common causes: the package is not installed in the mypy environment and no bundled stubs and the stub package is absent. mypy resolves imports against the environment it runs in; if the dependency is missing there, it cannot find the module.
How do I fix mypy "Cannot find implementation or library stub" in CI?
There are 2 fixes depending on which cause you have: install the package and its stubs for mypy and let mypy install missing stubs. Work through them in order, since the first is the most common.
What does mypy "Cannot find implementation or library stub" in CI actually mean?
mypy fails with "error: Cannot find implementation or library stub for module named 'X' [import-not-found]" and a hint to install the package or stubs.
How do I stop mypy "Cannot find implementation or library stub" in CI happening again?
Install your full dependency set in the mypy CI environment. The prevention section lists 3 changes that keep it from recurring.
