mypy "Cannot find implementation or library stub for module" in CI

mypy could not locate a module to type-check it - neither its source nor a stub package was found on mypy’s search path. Usually the package is not installed in the type-checking environment, the path is misconfigured, or the package ships no types.

What this error means

mypy fails with error: Cannot find implementation or library stub for module named "X" [import-not-found] and a hint about the path config. It is deterministic and tied to what mypy can import, not to runtime behavior.

mypy output

app/main.py:3: error: Cannot find implementation or library stub for module
named "requests"  [import-not-found]
app/main.py:3: note: See https://mypy.rtfd.io/en/stable/running_mypy.html#missing-imports

Common causes

The package (or its stubs) is not installed

mypy resolves imports from the environment it runs in. If the dependency - or its types-* stub package - is not installed there, mypy cannot find the module.

First-party module not on mypy’s path

For your own modules, a src-layout without the package installed, or a missing mypy_path/MYPYPATH, leaves mypy unable to locate the implementation.

How to fix it

Install the package and its stubs

Install dependencies (and types-* stubs) into the same environment mypy uses.

Terminal

pip install -r requirements.txt
pip install types-requests   # stubs for an untyped library
mypy app/

Configure paths or ignore truly untyped imports

Set the source path for first-party code, or ignore a specific untyped third-party module when no stubs exist.

pyproject.toml

[tool.mypy]
mypy_path = "src"

[[tool.mypy.overrides]]
module = ["some_untyped_pkg.*"]
ignore_missing_imports = true

How to prevent it

Run mypy in the same environment where dependencies are installed.
Install types-* stub packages for untyped libraries.
Set mypy_path for src-layout first-party code.