mypy

What it is

mypy is the reference implementation of PEP 484 static type checking for Python, originally written by Jukka Lehtosalo and maintained by a community core team with sponsorship from Dropbox (the largest historical user). It reads type annotations and reports type errors without running the program — wrong argument types, missing returns, None-dereferences, incompatible overrides.

It's a gradual type checker: it tolerates un-annotated code and only checks what you tell it to. --strict flips that default and demands annotations everywhere.

Install

pip install mypy

Output: (none — exits 0 on success)

uv add --dev mypy

Output: dependency added to the dev group in pyproject.toml

poetry add --group dev mypy

Output: updated lockfile + dev install

pipx install mypy

Output: installed to isolated venv, mypy CLI on PATH. Caveat: mypy needs to import your project's dependencies to type-check them — pipx-installed mypy can't see your project venv, so you usually want mypy inside the project venv, not as a pipx-global.

Versioning & Python support

• Current line is 1.x (mypy hit 1.0 in 2023 after years of 0.x releases).
• Minor-version cadence is roughly every 2–3 months. Releases can introduce stricter checks — pin in CI and bump deliberately.
• Recent releases run on Python 3.8+ and can check code targeting any version via --python-version 3.7..3.12. The runtime and the check target are independent.
• PEP 695 (new generic syntax in Python 3.12) is supported but only on the matching --python-version.
• Mypy follows roughly semver — major-version bumps signal genuine breakage in the public API.

Package metadata

• Maintainer: python/mypy GitHub org (community core team)
• Project home: github.com/python/mypy
• Docs: mypy.readthedocs.io
• PyPI: pypi.org/project/mypy
• License: MIT
• Governance: community core team; Dropbox historically the primary corporate sponsor
• First released: 2012
• Downloads: tens of millions per month

Optional dependencies & extras

mypy bundles typeshed — the third-party repository of type stubs for the stdlib and many popular packages. For packages not in typeshed, install the per-package types-* stub package (e.g. types-requests, types-PyYAML):

pip install types-requests types-PyYAML

Output: stub packages installed; mypy now type-checks import requests. Not all packages have stubs — projects that ship py.typed markers don't need them, and obscure libraries simply aren't covered.

Core deps: typing-extensions, mypy-extensions, tomli (on Python < 3.11).

Alternatives

Common gotchas

1. --strict is a meta-flag. It enables roughly ten individual rules (--disallow-untyped-defs, --disallow-incomplete-defs, --warn-return-any, --no-implicit-optional, …). Read mypy --help | grep strict to see the current bundle. Don't enable --strict everywhere day one — it floods CI.
2. PEP 695 generic syntax only on 3.12+. Writing class Box[T]: ... requires --python-version 3.12 and a 3.12+ interpreter. On older targets, fall back to TypeVar.
3. Stub packages don't always exist. pip install types- then <Tab> won't find every library. For unstubbed packages with no py.typed, mypy treats imports as Any — set [[tool.mypy.overrides]] with ignore_missing_imports = true to silence the warning.
4. # type: ignore without an error code is too broad. Use # type: ignore[arg-type] so future errors of other types still surface. Enable warn_unused_ignores = true to catch dead # type: ignore lines.
5. Cache lives in .mypy_cache/. Stale cache occasionally produces ghost errors after a major refactor or version bump. rm -rf .mypy_cache is the standard remedy.
6. Any is contagious. A single Any-typed function return spreads through every downstream call site, silently disabling checks. Use --warn-return-any and --disallow-any-expr (via --strict) to catch this.
7. mypy needs to import your code's deps. Unlike a pure-syntactic linter, it actually executes module-level code during analysis. Side-effecting top-level code in dependencies can break type-checking in surprising ways — keep imports lazy.

Configuration & layout patterns

mypy's config lives in pyproject.toml under [tool.mypy] (modern) or mypy.ini / setup.cfg (legacy — supported but not canonical). Per-module overrides use [[tool.mypy.overrides]] arrays:

[tool.mypy]
python_version = "3.12"
strict = true
warn_unused_ignores = true
warn_redundant_casts = true
show_error_codes = true
show_column_numbers = true
pretty = true
exclude = ['migrations/', 'generated/']

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

[[tool.mypy.overrides]]
module = ["legacy_lib.*", "untyped_third_party"]
ignore_missing_imports = true

[[tool.mypy.overrides]]
module = "mypkg.legacy.*"
ignore_errors = true

Strategies by codebase shape:

• New project, strict from day one. strict = true globally; never relax. Cheap to maintain because every commit stays clean.
• Existing untyped project, gradual. Start with strict = false and a tiny [[tool.mypy.overrides]] allowlist of modules with strict = true. Expand the allowlist module-by-module. Use ignore_errors = true for legacy code you'll touch later.
• Library code with py.typed marker. Ship a py.typed empty file in the package; mypy then trusts the in-tree type info for downstream users. Without this, your library's types are invisible.
• Monorepo. Single pyproject.toml config at the root; mypy_path = "src/pkg1/src:src/pkg2/src" tells mypy where to find each sub-package. Run mypy from the repo root with explicit module names: mypy -p mypkg.

The mypy_path setting is the most common monorepo gotcha — without it, mypy can't find packages that aren't installed. The src/ layout requires either pip install -e . per sub-package or explicit mypy_path.

Real-world recipes

Gradual typing on a 100k-line codebase

# pyproject.toml — phase 1: enable mypy without exploding CI
[tool.mypy]
python_version = "3.12"
ignore_missing_imports = true
follow_imports = "silent"
disallow_untyped_defs = false

[[tool.mypy.overrides]]
module = "mypkg.core.*"
strict = true

Run mypy in CI on the core module only at first. Once green, add mypkg.api.*, then mypkg.workers.*. Six months in, flip the top-level strict = true and adjust the remaining overrides.

The --strict toggle is a meta-flag expanding to ~10 individual rules. The modern strict set includes: warn_unused_configs, disallow_any_generics, disallow_subclassing_any, disallow_untyped_calls, disallow_untyped_defs, disallow_incomplete_defs, check_untyped_defs, disallow_untyped_decorators, no_implicit_optional, warn_redundant_casts, warn_unused_ignores, warn_return_any, no_implicit_reexport, strict_equality.

Type-narrowing a Union

from typing import TypeGuard

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

def process(items: list[object]) -> None:
    if is_str_list(items):
        # mypy now treats items as list[str] inside this block
        print(", ".join(items))

TypeGuard (PEP 647) lets mypy narrow a Union based on a custom predicate. The newer PEP 742 TypeIs (Python 3.13+) is stricter — recommended for new code if you can target 3.13.

Protocol for duck-typed APIs

from typing import Protocol

class SupportsClose(Protocol):
    def close(self) -> None: ...

def shutdown(resource: SupportsClose) -> None:
    resource.close()

Protocol types are structural — any class with a matching close() method satisfies SupportsClose without inheriting. This is the typed-Python equivalent of duck typing.

TypedDict for JSON shapes

from typing import TypedDict, NotRequired

class UserPayload(TypedDict):
    id: int
    name: str
    email: NotRequired[str]  # optional field

def update_user(payload: UserPayload) -> None:
    ...

mypy enforces both the presence of required fields and the absence of unknown ones. total=False (class-level) makes all fields optional; NotRequired (PEP 655) is per-field, more granular.

Per-module # type: ignore[code]

import legacy_module  # type: ignore[import-not-found]

result: int = legacy_module.compute()  # type: ignore[no-any-return]

Always include the error code — # type: ignore without one silences everything in that line, hiding new errors. warn_unused_ignores = true flags ignores that no longer suppress anything (i.e. the underlying issue is now fixed).

Performance tuning

mypy is famously the slow link in any Python CI pipeline. Levers, in impact order:

• dmypy (daemon mode). Long-running mypy process that incrementally re-checks changed files. ~10× faster on warm cache. dmypy start, dmypy check src/, dmypy stop. Editor integrations (PyCharm, VS Code via Pylance with --useTypingExtensions) use the daemon transparently.
• Cache lives in .mypy_cache/. Per-Python-version, content-hashed. Add to .gitignore; cache in CI with actions/cache@v4. Speed-up: 5–20× depending on change scope.
• --sqlite-cache stores the cache in SQLite instead of many small files. Faster on Windows (small-file I/O is slow) and network filesystems.
• follow_imports = "silent" stops mypy from analysing dependencies' source. Trades coverage for speed. Pair with ignore_missing_imports = true for untyped third-party deps.
• --no-incremental disables the cache. Useful only for debugging spurious behaviour — never in normal use.
• Parallel by module — mypy itself is not parallel within a run, but you can split CI: mypy -p mypkg.core &; mypy -p mypkg.api &; wait. Effective up to 4 splits.
• --cache-fine-grained enables daemon-level cache stability across restarts. Experimental but solid.

For 1M+-line codebases, the daemon plus aggressive caching is the difference between a 30-second incremental check and a 5-minute full re-analysis.

Version migration guide

mypy's major-version bumps are conservative; minor bumps regularly tighten checks. Recent inflection points:

mypy 1.13 (2024)

• TypeIs (PEP 742) supported as a stricter alternative to TypeGuard.
• Improved match statement narrowing on complex patterns.

mypy 1.10 (2024)

• Pattern-matching narrowing improved; previously many patterns were inferred too loosely.
• --enable-incomplete-feature=NewGenericSyntax for PEP 695 became default-on for 3.12 target.

mypy 1.0 (2023)

• Long-anticipated 0.x → 1.0 bump. Mostly signalled stability rather than breakage. Some long-deprecated flags removed.

Recurring patterns across releases:

• Stub package shims — when an upstream library adds py.typed, the corresponding types-* shim package is deprecated. mypy emits a warning; remove the shim.
• Strictness defaults — new strict sub-flags are added periodically. A clean run on mypy 1.10 may emit new warnings on 1.13.
• --python-version deprecation cycle — when Python EOL hits, that target version emits a deprecation warning for 2 minor releases, then is removed.

Upgrade pattern:

1. Pin mypy + every types-* package exactly.
2. Bump on a deliberate cadence. Read Changelog.md — the "Stricter checks" section is the relevant one.
3. After the bump, run mypy --strict src/ once; fix or # type: ignore[new-code] each new error.
4. If a stub package is now redundant, remove from dev deps.

Plugin & rule ecosystem

mypy supports plugins — Python modules that hook into the type checker to add custom inference rules. Used by:

Enable in pyproject.toml:

[tool.mypy]
plugins = ["pydantic.mypy", "mypy_django_plugin.main"]

[tool.django-stubs]
django_settings_module = "myproj.settings"

Plugins are tied to mypy major versions; bump them together.

Troubleshooting common errors

mypy --show-error-codes --show-error-context is the surgical flag combo for unclear errors — it includes the error code (so you can # type: ignore[<code>]) and surrounding code.

Ecosystem integrations

mypy sits alongside, not inside, most other tools:

• pyright (Microsoft) — competitor type checker. Powers Pylance in VS Code. Faster (TypeScript-native, multithreaded). Different inference algorithm — pyright is generally stricter and faster. Some projects run both; pyright in editors, mypy in CI.
• ty (Astral) — in-development Rust type checker, mypy-compatible target. Promises ruff-like speed. Watch this space.
• basedmypy — fork of mypy with stricter defaults and additional # type: ignore lint rules.
• pyre (Meta) — built for huge codebases. OCaml-based; sparse public docs.
• pytype (Google) — lattice-based inference; types from untyped code. Slower; Linux/macOS only.
• pre-commit — pre-commit/mirrors-mypy is the canonical hook source. Heavy; often gated to stages: [push] instead of [commit].
• dmypy — daemon mode for incremental editor checks.
• mypyc — compiles type-annotated Python to C. Different tool; shares the source repo. Black uses mypyc to compile itself.

CI integration

name: types
on: [push, pull_request]
jobs:
  mypy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - uses: actions/cache@v4
        with:
          path: .mypy_cache
          key: mypy-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}
      - run: pip install -e ".[type-check]"
      - run: mypy src/ tests/

Key choices:

• Cache .mypy_cache/ — biggest single CI speedup. Hash on pyproject.toml so dep changes invalidate.
• Install the project (pip install -e .) — mypy imports your code to type-check it. Stub-only checks miss runtime-side type info.
• Pin mypy version in the extras group: [project.optional-dependencies] type-check = ["mypy==1.13.0", "types-requests"].
• Single Python version — mypy's behaviour depends on python_version config, not the runner version. No matrix needed.

For monorepos, parallelise per package:

strategy:
  matrix:
    package: [api, core, workers]
steps:
  - run: mypy -p ${{ matrix.package }}

Each cell has its own .mypy_cache/. Net wall-clock time drops to the slowest cell.

When NOT to use this

• Tiny scripts — a 100-line script doesn't need static type checking. The ratio of annotation effort to bug catch is poor.
• Highly dynamic libraries — code that uses __getattr__, eval, dynamic class creation extensively. mypy hits its limits here; pyright sometimes does better.
• Codebases that mix typed Python with heavy C extensions without stubs. The unstubbed C boundary throws away type info; the value of mypy upstream of that boundary is reduced.
• Editor-only typing. If you only want IDE hints, pyright via Pylance is faster and editor-native. mypy's value is CI-enforced gradual typing.
• Pre-PEP 484 codebases that can never afford a typing pass. Gradual is possible but the discipline is real — without commitment, you accumulate # type: ignore and call it typed.

See also

• Python: mypy — strict-mode configuration, error codes, # type: ignore patterns
• Concept: API — type-checking as contract enforcement
• Packages: pip-ruff — lint alongside type-check
• Packages: pip-pre-commit — run mypy on every commit