Mypy — Optional Static Type Checker for Python

Introduction

Mypy is the original static type checker for Python, created by Jukka Lehtosalo and maintained under the Python organization. It reads PEP 484 type annotations and checks your code for type consistency without running it, bridging the gap between Python's dynamic nature and the safety of static typing.

What Mypy Does

• Analyzes type annotations across modules and packages to detect type errors
• Supports gradual typing so you can add annotations incrementally
• Checks third-party library types via stub files and the typeshed repository
• Provides a daemon mode (dmypy) for fast incremental checks in large codebases
• Generates reports on type coverage to track adoption progress

Architecture Overview

Mypy parses Python source files into an AST, resolves imports, and builds a semantic model of your program. It then runs a type inference engine that propagates types through assignments, function calls, and control flow. The checker uses union types, generics, protocols, and literal types as defined in the typing module. An optional mypyc compiler can compile type-annotated Python to C extensions for performance.

Self-Hosting & Configuration

• Install via pip install mypy and run against individual files or entire packages
• Configure in mypy.ini, setup.cfg, or pyproject.toml under [tool.mypy]
• Use --strict to enable all optional strictness flags at once
• Add per-module overrides with [[tool.mypy.overrides]] for gradual adoption
• Install type stubs with mypy --install-types or manually via types-* packages

Key Features

• Gradual typing lets untyped and typed code coexist seamlessly
• Supports advanced types: generics, protocols, TypedDict, ParamSpec, TypeVarTuple
• Daemon mode (dmypy) caches analysis results for sub-second incremental checks
• Plugins for Django, SQLAlchemy, attrs, and Pydantic provide framework-aware checking
• mypyc compiles annotated modules to native C extensions for runtime speedups

Comparison with Similar Tools

• Pyright — Microsoft's type checker, faster on large codebases; Mypy is the reference implementation with broader plugin ecosystem
• Pytype — Google's type checker with type inference for unannotated code; Mypy requires explicit annotations for full checking
• Ruff — a linter and formatter but not a type checker; complements Mypy rather than replacing it
• Pyre — Meta's type checker optimized for large monorepos; Mypy has wider community adoption
• beartype — runtime type checking via decorators; Mypy checks statically without runtime overhead

FAQ

Q: Do I need to annotate every function? A: No. Mypy supports gradual typing. You can start with a few critical modules and expand coverage over time.

Q: Does Mypy slow down my code at runtime? A: No. Mypy runs as a separate analysis step. Type annotations have no runtime performance impact in standard Python.

Q: How do I handle libraries without type stubs? A: Use --ignore-missing-imports or install community stubs. You can also write your own .pyi stub files.

Q: Can I use Mypy in CI? A: Yes. Run mypy --strict in your CI pipeline and treat non-zero exit codes as failures.

Sources

• https://github.com/python/mypy
• https://mypy.readthedocs.io/en/stable/