Mypy: Optional Static Typing for Python

1.19.1 verified Tue May 12 auth: no python install: verified quickstart: stale

Mypy is a static type checker for Python, enabling optional static typing to improve code quality and maintainability. As of version 1.19.1, it supports Python 3.9 and later, with regular updates and a stable release cadence.

pip install mypy

Common errors

error Cannot find implementation or library stub for module named 'foo' ↓

cause Mypy cannot locate the Python module 'foo' or its associated type stubs (.pyi files), often because it's a third-party library without stubs, a local module not on Mypy's search path, or not installed in the environment Mypy is checking.

fix

Install the module (e.g., pip install foo), install its type stubs (e.g., pip install types-foo or mypy --install-types), add the module's parent directory to MYPYPATH, or configure mypy.ini with ignore_missing_imports = True for the specific module (e.g., [mypy-foo.*] ignore_missing_imports = True).

error Incompatible types in assignment (expression has type "X", variable has type "Y") ↓

cause You are attempting to assign a value of one type (expression type 'X') to a variable that has been explicitly or implicitly typed as another incompatible type ('Y').

fix

Ensure the assigned value's type matches the variable's expected type, or explicitly annotate the variable with a Union type if it can legitimately hold different types, or use cast() if you are certain about the type and want to override Mypy.

error Need type annotation for 'variable_name' ↓

cause Mypy is unable to infer the precise type of a variable, typically occurring with empty collections (e.g., `[]`, `{}`) or when `--disallow-untyped-defs` or `warn_incomplete_defs` is enabled, requiring an explicit type hint.

fix

Add an explicit type annotation to the variable, especially for empty containers (e.g., my_list: list[str] = [] or my_dict: dict[str, int] = {}).

error Name 'name' is not defined ↓

cause Mypy detects a reference to a name (variable, function, class, or module) that has not been defined or properly imported within the current scope. This often indicates a typo or a missing import.

fix

Correct any typos in the name, ensure the item is imported from the correct module, or define the name before its first use.

error Function does not return a value ↓

cause A function or method is annotated with a return type other than `None` (or implicitly expected to return a value), but there is a code path where it implicitly returns `None` (e.g., by reaching the end of the function without an explicit `return` statement).

fix

Ensure all code paths within the function explicitly return a value consistent with its return type annotation, or change the return type annotation to None if the function is not meant to return anything.

Warnings

breaking Mypy 1.9 introduced breaking changes due to an updated typeshed version, dropping support for Python 3.7. ↓

fix Upgrade to Python 3.8 or later to maintain compatibility.

gotcha Using 'Final' and 'TypedDict' from 'typing' requires Python 3.8 or later; for earlier versions, install 'typing_extensions'. ↓

fix Install 'typing_extensions' to use these features on older Python versions.

gotcha Mypy reported a 'Missing target' error, indicating that it was called without specifying any files, modules, or packages to type-check. This is a usage error. ↓

fix Ensure that the 'mypy' command is followed by the path to the files, modules, or packages you intend to type-check, for example: 'mypy my_script.py' or 'mypy -m my_package'.

breaking Mypy failed because no target module, package, or files were specified. The 'mypy' command requires at least one argument indicating what to type-check. ↓

fix Ensure the 'mypy' command is invoked with a target, such as 'mypy your_module.py', 'mypy --package your_package', or 'mypy --module your_module'.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.01s 76.7M

3.10 slim (glibc) - - 0.00s 76M

3.11 alpine (musl) - - 0.01s 81.6M

3.11 slim (glibc) - - 0.01s 81M

3.12 alpine (musl) - - 0.01s 73.5M

3.12 slim (glibc) - - 0.01s 73M

3.13 alpine (musl) - - 0.01s 73.3M

3.13 slim (glibc) - - 0.01s 72M

3.9 alpine (musl) - - 0.01s 72.6M

3.9 slim (glibc) - - 0.01s 71M

Imports

Final
```
from typing import Final
```
Use 'Final' from 'typing' to indicate constants; 'typing_extensions' is needed for Python versions prior to 3.8.
TypedDict
```
from typing import TypedDict
```
Use 'TypedDict' from 'typing' for defining typed dictionaries; 'typing_extensions' is needed for Python versions prior to 3.8.

Quickstart stale last tested: 2026-04-23

Integrate Mypy into your Python application by importing 'mypy.api' and calling the 'run' function with command-line arguments. This allows programmatic access to Mypy's type checking capabilities.

import sys
from mypy import api

result = api.run(sys.argv[1:])

if result[0]:
    print('\nType checking report:\n')
    print(result[0])  # stdout

if result[1]:
    print('\nError report:\n')
    print(result[1])  # stderr

sys.exit(result[2])  # exit status