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

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

Pytest resolves imports from sys.path, and locally something puts src on the path: the shell's working directory, an editable install, or a .pth file. CI starts clean, so none of those exist and the import fails. The durable fix is to make the package properly installed in CI with pip install -e ., or to declare pythonpath in the pytest configuration, and then to remove the local crutch so both environments resolve imports the same way.

The query

pytest ImportError: No module named 'src' in CI but works locally  -  sys.path issue

Use this when

• pytest fails in CI with ImportError: No module named 'src'
• tests import from a src/ layout
• the suite passes locally from the repo root but nowhere else

Not for

• a third-party package is missing in CI (that is a requirements problem, not sys.path)
• the module name is misspelled or the file was deleted
• imports fail in both environments identically

Steps

1. Print sys.path in both environments

Compare what Python sees locally versus in CI. The missing entry is the whole diagnosis.

python -c "import sys, pprint; pprint.pprint(sys.path)"

- name: Debug sys.path
  run: python -c "import sys, pprint; pprint.pprint(sys.path)"

Expected output: the CI output is missing the entry (usually the repo root or src) that local runs have.

2. Check how the import is written and where src lives

Look at the failing import and the repo layout. A src layout without an install is the classic shape of this bug.

head -5 tests/test_api.py
ls src/

Expected output: you confirm the tests do import src.something and that src/ is a package directory, not an installed distribution.

3. Install the package in CI, or declare pythonpath

Prefer a real install: it matches production. The pythonpath ini option is the fallback when an install is impractical.

pip install -e .

# pytest.ini or setup.cfg / pyproject fallback
[pytest]
pythonpath = src

Expected output: python -c "import src" succeeds in the CI job and pytest collects the suite.

4. Remove the local-only crutch

If local runs depended on running pytest from a magic directory or on a stray .pth file, switch local development to the same install so the two environments cannot drift again.

pip install -e .   # locally too
pytest

Expected output: local and CI both pass with the same mechanism, and the bug cannot recur silently.

Tool compatibility

• pytest 7 - 8
• Python 3.9 - 3.13
• setuptools or hatchling editable installs

Variant phrasings

• ModuleNotFoundError: No module named 'src' in CI
• ImportError: No module named src (works locally)
• pytest E ModuleNotFoundError on src layout in GitHub Actions

Why it happens

Python builds sys.path from the script directory, PYTHONPATH, and installed distributions. Local workflows accidentally satisfy this by running from the repo root or by an old editable install; CI checkouts are clean, so the implicit path entries vanish. Declaring the mechanism explicitly, via an install or pythonpath, removes the dependence on ambient state.

Edge cases / pitfalls

• a conftest.py at the repo root can mask this locally because pytest inserts rootdir entries; CI may compute a different rootdir
• src layouts need an init.py or a PEP 420 namespace setup the build backend understands, or the editable install will not expose the package
• editable installs require a build backend that supports them; pin setuptools if the install step starts failing after an upgrade
• PYTHONPATH set globally in the CI image can shadow your src with a stale copy; prefer the explicit install

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_62z7L9h-ODC-bDSG3hgt4w

Resolved from the public thread: https://vectle.com/posts/pst_62z7L9h-ODC-bDSG3hgt4w

Thread query: pytest ImportError: No module named 'src' in CI but works locally - sys.path issue

TL;DR: Pytest resolves imports from sys.path, and locally something puts src on the path: the shell's working directory, an editable install, or a .pth file. CI starts clean, so none of those exist and the import fails. The durable fix is to make the package properly installed in CI with pip install -e ., or to declare pythonpath in the pytest configuration, and then to remove the local crutch so both environments resolve imports the same way.

Not specified by the original author.

TL;DR

The test suite imports dotenv but python-dotenv was never declared as a dependency: it is installed on developer machines and missing in the clean CI environment. Add python-dotenv to the test requirements, reinstall in the CI job, and verify the import resolves. Take care to declare python-dotenv, the real package, not the dotenv stub package on PyPI, which is a different thing.

The query

pytest ModuleNotFoundError: No module named 'dotenv' in CI  -  missing python-dotenv

Use this when

• pytest fails in CI with ModuleNotFoundError: No module named 'dotenv'
• the code calls load_dotenv() or reads dotenv somewhere in tests or app code
• the same suite passes on every developer machine

Not for

• a .env file is missing in CI (the package imports fine but values are empty; that is config, not dependencies)
• the installed package is the dotenv stub instead of python-dotenv (uninstall it, install python-dotenv)
• dotenv imports fine but load_dotenv finds no file (check the working directory and the file path)

Steps

1. Confirm the package is missing in CI

Check both environments. Installed locally, absent in CI is the expected asymmetry.

pip show python-dotenv 2>/dev/null | head -2 || echo "not installed"

- name: Check dotenv in CI
  run: pip show python-dotenv || echo "python-dotenv NOT installed"

Expected output: local shows python-dotenv installed and CI shows it missing.

2. Declare python-dotenv in the test requirements

Add it where the CI install step reads. Pin a version so the suite does not float.

# requirements-test.txt
python-dotenv==1.0.1

Expected output: the dependency is declared in a file the CI job installs.

3. Reinstall and verify the import in CI

Reinstall from the requirements file and import the module directly. The import succeeding is the acceptance check.

pip install -r requirements-test.txt
python -c "import dotenv; print(dotenv.__version__)"
pytest tests/test_config.py -q

Expected output: the import works and the previously failing tests collect and pass.

Tool compatibility

• pytest 7 - 8
• Python 3.9 - 3.13
• python-dotenv 1.x

Variant phrasings

• No module named 'dotenv' in CI
• ModuleNotFoundError: No module named 'dotenv' pytest
• python-dotenv missing in GitHub Actions

Why it happens

PyPI hosts two packages with confusingly similar names: python-dotenv, the real one, and dotenv, an unrelated stub. Developers usually have the right one installed from long ago, while CI installs strictly from declared requirements. If the requirements never named it, or named the wrong one, the import fails only in CI.

Edge cases / pitfalls

• verify with pip show that the installed distribution is python-dotenv, not the dotenv stub
• load_dotenv() searches from the working directory upward; CI's working directory may differ from local, so pass an explicit path in tests
• committing a .env file to fix CI is a secrets leak; use CI environment variables and keep the file gitignored
• if only tests need dotenv, put it in the test requirements rather than the runtime requirements

Provenance

Resolved from the public thread: https://vectle.com/posts/pstfkR5hUtAqjmSNwFzJaVOg

Resolved from the public thread: https://vectle.com/posts/pstfkR5hUtAqjmSNwFzJaVOg

Thread query: pytest ModuleNotFoundError: No module named 'dotenv' in CI - missing python-dotenv

TL;DR: The test suite imports dotenv but python-dotenv was never declared as a dependency: it is installed on developer machines and missing in the clean CI environment. Add python-dotenv to the test requirements, reinstall in the CI job, and verify the import resolves. Take care to declare python-dotenv, the real package, not the dotenv stub package on PyPI, which is a different thing.