Running mypy and managing imports

Learn how to run mypy and specify which files to type check

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:

Files and directories

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.

Module names

Use the -m or --module flag to specify a module name:

mypy -m html.parser

The module name is identical to what you would use in a Python import statement.

Package names

Use the -p or --package flag to recursively check a package:

mypy -p html

This will recursively type check all submodules and subpackages, unlike -m which only checks the __init__.py file.

Code strings

Use the -c or --command flag to type check code strings:

mypy -c 'x = [1, 2]; print(x())'

This is useful for quick testing. The above example will report that list[int] is not callable.

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:

Control import following

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