Skip to content

mypy: Python Static Type Checker

by Tim Hopper · Markdown
Type Checking

mypy is a static type checker for Python that analyzes type annotations to detect bugs before runtime. It has been the default Python type checker since 2012 and has the broadest ecosystem support of any Python type checking tool.

When to use mypy

Use mypy when you want to catch type-related bugs before runtime by adding static type checking to a Python project. It is the most established Python type checker with broad ecosystem support, making it a reliable default for projects that are adopting type annotations incrementally. For faster checking or tighter VS Code integration, consider pyright; for an emerging alternative from the creators of Ruff, see ty.

Key Features

  • Gradual typing: add type annotations incrementally to an existing codebase. Unannotated functions are skipped by default unless --check-untyped-defs or strict mode is enabled.
  • Type inference: deduces types from assignments, return values, and usage patterns when explicit annotations are absent.
  • Generic types, unions, protocols: supports parameterized types (list[int]), union types (str | int), structural subtyping via Protocol, and TypedDict for typed dictionaries, including closed TypedDicts (PEP 728) that reject undeclared keys.
  • Type stubs: works with typeshed and custom stub files for libraries that don’t ship inline annotations.
  • mypyc compilation: mypy includes mypyc, a compiler that translates type-annotated Python into C extensions for significant runtime speedups.
  • Parallel type checking: pass --num-workers N (or set the MYPY_NUM_WORKERS environment variable) to type-check across multiple worker processes. Parallel mode implicitly enables the native parser.
  • Native parser: an optional parser based on Ruff’s parser, available via uv add --dev "mypy[native-parser]" and the --native-parser flag.
  • Python 3.14 support: handles t-strings (PEP 750) and ships mypyc-accelerated wheels for free-threading builds.

Pros

  • Most established type checker with the broadest library compatibility and community resources
  • Gradual adoption path via per-module configuration overrides
  • mypyc compiler can speed up runtime performance of type-annotated code
  • Parallel checking and an optimized binary cache close the performance gap with newer tools

Cons

  • Skips unannotated functions by default, which surprises users who expect it to catch obvious errors everywhere (see how to configure mypy strict mode to enable stricter checking)
  • No built-in language server; editor integration relies on third-party plugins or pairing with pyright or ty
  • Slower than ty on large codebases, though roughly on par with pyright on current versions
  • Struggles with highly dynamic Python patterns

Installation and Usage 

# Add as a dev dependency
uv add --dev mypy

# Check a single file
uv run mypy example.py

# Check multiple files or directories
uv run mypy src/ tests/

# Enable stricter checking
uv run mypy --strict example.py

# Type-check in parallel
uv run mypy -n 8 src/

Configuration

mypy reads configuration from mypy.ini, .mypy.ini, setup.cfg, or pyproject.toml (under [tool.mypy]). The minimum --python-version target is 3.10. --local-partial-types and --strict-bytes (PEP 688) are enabled by default; projects upgrading from 1.x may see new errors from these stricter defaults.

Per-module overrides let you treat vendored code or test files differently from application code:

pyproject.toml
[tool.mypy]
python_version = "3.12"
strict = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

Learn More

Last updated on
mkdocstringsnox