Skip to main content
This guide explains how to specify which files you want mypy to type check, how mypy discovers imported modules, and how to handle common issues.

​
Specifying code to be checked

Mypy provides several ways to specify which files to type check:
Pass paths to Python files and directories directly:
mypy file_1.py foo/file_2.py file_3.pyi some/directory
Mypy will recursively type check the entire contents of any provided directories.

​
Multiple targets

You can specify multiple packages and modules on the command line: 
mypy --package p.a --package p.b --module c

​
Reading from a file

You can read additional command-line arguments from a file using the @ prefix: 
mypy @file_of_files.txt
This is more portable than using shell syntax like mypy $(cat file_of_files.txt).

​
Using configuration files

You can use the files option in your mypy.ini file to specify which files to check, then simply run mypy with no arguments.

​
How mypy finds imports

1

Check for stub files

Mypy first looks for stub files (.pyi) in the same directory as the module.
2

Search MYPYPATH

If not found, mypy searches directories in the MYPYPATH environment variable.
3

Check installed packages

Mypy looks for installed packages that provide type information (PEP 561).
4

Search typeshed

Finally, mypy searches the bundled typeshed for standard library stubs.

​
Module discovery

Mypy uses an algorithm similar to Python’s import system to locate modules: 
# Set custom module search path
export MYPYPATH=~/work/myproject/stubs

# Run mypy
mypy myproject
Mypy resolves imports relative to the current working directory by default.

​
Mapping file paths to modules

When you pass file paths to mypy, it maps them to module names: 
# These are equivalent:
mypy src/myapp/main.py
mypy -m myapp.main  # If src is in PYTHONPATH

​
Following imports

By default, mypy follows all imports and type checks imported modules:
Use follow_imports configuration to control this behavior:
  • normal - Follow imports and type check (default)
  • silent - Follow imports but suppress errors
  • skip - Don’t follow imports at all
  • error - Treat imports as errors
[mypy-untyped_package.*]
follow_imports = skip

​
Common import issues

Avoid pointing MYPYPATH to the standard library or site-packages. This will likely cause many errors and may crash mypy.

​
Cannot find module

If mypy reports it cannot find a module:
  1. Check the module is installed in the environment where you run mypy
  2. Install stub packages for third-party libraries (e.g., types-requests)
  3. Use ignore_missing_imports = True for modules you can’t type check
  4. Set MYPYPATH to include custom stub directories

​
Namespace packages

For namespace packages without __init__.py: 
mypy --namespace-packages mypackage

​
Best practices

Use configuration files

Store mypy settings in mypy.ini or pyproject.toml for consistency across your team.

Pin mypy version

Pin mypy version in your requirements to ensure consistent behavior in CI.

Run in CI

Add mypy to your continuous integration pipeline to catch type errors early.

Use incremental mode

Enable incremental mode for faster repeated checks on large codebases.

​
Performance tips

Use daemon mode (dmypy) for much faster incremental checks during development:
dmypy run -- myproject
For large projects:
  • Use --cache-dir to specify a cache location
  • Enable incremental mode (on by default)
  • Consider using remote caching for CI environments
  • Use --skip-version-check if you’re certain dependencies haven’t changed

Build docs developers (and LLMs) love

Get started for freeTalk to us