mypy "Cannot find implementation or library stub" in CI

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.

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

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

1. Install the runtime package in the same environment mypy uses.
2. Add the types-* stub package if the library ships no inline types.
3. Re-run mypy.

pip install requests types-requests
mypy app/

Let mypy install missing stubs

Use mypy's install-types to fetch known stub packages automatically.

mypy --install-types --non-interactive app/

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.

Related guides