mypy error: cannot find implementation or library stub for module in CI

TL;DR

mypy cannot find type information for a third-party module in CI. Locally the stubs exist; in CI they were never installed. Install the matching types package in the CI environment, or tell mypy to ignore that specific import. The code is fine - the environment is incomplete.

The error

mypy error: cannot find implementation or library stub for module in CI

Steps

1. Identify the module

Read the full error line. It names the module mypy cannot resolve. Expected output: you know exactly which import is missing stubs.

2. Check what is installed locally versus CI

pip show types-requests

Use the types package matching the module. Run it locally and in CI. Expected output: installed locally, missing in CI. That gap is the bug.

3. Add the types package to CI dependencies

Add the matching types- package (for example types-requests for the requests library) to the dev or test requirements file that CI installs. Expected output: CI installs the stubs alongside the library.

4. Or ignore that specific import

If no stubs exist for the module, silence just that import in the mypy config:

[mypy-requests.*]
ignore_missing_imports = True

Expected output: mypy skips the unresolvable import without hiding other errors.

5. Pin the mypy version in CI

Version drift changes stub resolution behavior. Pin the same mypy version locally and in CI. Expected output: both environments resolve imports identically.

6. Re-run the type check

Expected output: mypy exits 0 with no missing-stub errors.

When to use

• The exact missing-stub error in CI
• Type checking passes locally but fails in CI
• A new third-party dependency was just added

When not to use

• Genuine type errors in your own code
• mypy config file errors
• Import errors at runtime (different problem)

Tool compatibility

• mypy 1.x
• typeshed and the types stub packages on PyPI
• pip, poetry, and other Python installers

Variant phrasings

mypy cannot find stub for module in GitHub Actions

Same fix. The Actions environment is missing the types package.

mypy library stubs missing after adding dependency

Every new third-party import may need its types package. Add both together.

ignoremissingimports versus installing stubs

Installing stubs is better: it type-checks the library usage. Ignoring is the fallback when no stubs exist.

Why it happens

mypy needs type stubs for every imported module. Typeshed ships stubs for the standard library, but third-party stubs live in separate types packages that must be installed. Dev machines accumulate them over time; fresh CI environments do not.

Edge cases

• Namespace packages and plugins sometimes need explicit mypy plugin config beyond the stubs.
• A library that ships its own inline types needs no types package. Check before adding one.
• ignoremissingimports on a broad pattern hides real problems. Scope it to the single module.
• Stub version must match the library version loosely. A stale types package can report phantom errors.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3fSUGcUtXTNYjE-aMY68EA