mypy Cheat Sheet

1Install & run2.x

pip install mypy mypy src/★
Check a file, module, or package. Exit code is non-zero on errors (CI-friendly).
mypy --strict src/ · mypy --num-workers 8 src/★
--strict turns on all the strictness flags at once; --num-workers (mypy 2.0+) parallelizes for big codebases.
reveal_type(x) # mypy prints the inferred type, then remove it★
Debugging aid — no import needed. reveal_locals() for all locals. (Fails at runtime, so delete after.)
mypy --install-types · dmypy run -- src/ # daemon (fast re-checks)
Auto-install missing stub packages; dmypy keeps a warm daemon for near-instant re-runs.

2Annotate functions & varsthe syntax

def greet(name: str, times: int = 1) -> str: return name * times★
Params and return type. mypy checks callers pass the right types and that the body returns str.
count: int = 0 names: list[str] = []★
Variable annotations — usually inferred, but annotate empty containers so mypy knows the element type.
def log(msg: str) -> None: ...★
Functions with no return value are -> None. Under disallow_untyped_defs, every def needs annotations.
from collections.abc import Sequence, Iterable, Mapping★
Prefer abstract types for parameters (accept more) — take Iterable[int], return a concrete list[int].

3Collections & unionsmodern syntax

list[int] · dict[str, float] · tuple[int, str] · set[bytes]★
Built-in generics (3.9+) — no more typing.List. tuple[int, ...] for variable-length.
str | None # the modern Optional★
X | None (3.10+) == Optional[X]. int | str for a union. mypy forces you to handle the None case.
def f(x: int | None) -> int: if x is None: return 0 return x + 1 # here x is narrowed to int★
The #1 win: mypy tracks that x could be None and errors on x + 1 until you check.
type Vector = list[float] # type alias (3.12+)
Name a complex type once. (Older: Vector: TypeAlias = list[float].)

4Any, Callable, Literal, Finalspecial forms

from typing import Any x: Any = ... # opts OUT of checking — use sparingly★
Any is compatible with everything — it silences mypy. object is the safe "anything" that still requires narrowing.
from collections.abc import Callable cb: Callable[[int, str], bool]★
A function type: args list → return. Callable[..., T] for any args.
from typing import Literal mode: Literal["r", "w", "a"]★
Restrict to specific constant values — mypy rejects mode="x".
from typing import Final MAX: Final = 100 # can't be reassigned
Final = constant; ClassVar for class-level (non-instance) attributes.

5Generics & TypeVarreusable types

def first[T](items: list[T]) -> T: return items[0]★
PEP 695 syntax (3.12+): [T] declares a type variable inline — the return type follows the input's element type.
class Box[T]: def __init__(self, item: T) -> None: self.item = item★
Generic classes too. Box[int] then has item: int.
def f[T: (int, float)](x: T) -> T # constrained def g[T: Comparable](x: T) # bound
Constrain a TypeVar to specific types, or bound it to a supertype/Protocol.
# pre-3.12: from typing import TypeVar; T = TypeVar("T")
The classic form still works if you support older Python.

6Protocol & TypedDictstructural & dicts

from typing import Protocol class Readable(Protocol): def read(self) -> str: ...★
Structural typing (duck typing): anything with a matching read() satisfies Readable — no inheritance needed.
from typing import TypedDict class User(TypedDict): id: int; name: str★
Type a dict with fixed keys — great for JSON payloads. total=False or NotRequired[...] for optional keys.
@runtime_checkable # enables isinstance() on a Protocol
Add to a Protocol to allow runtime isinstance checks (structural, methods only).

7overload & moreprecise signatures

from typing import overload @overload def get(x: int) -> str: ... @overload def get(x: str) -> int: ...★
Different return types per input type. Provide the real implementation (unannotated overload) after the stubs.
from typing import NewType UserId = NewType("UserId", int) # distinct from plain int
A zero-cost distinct type to prevent mixing up ids and ints.
self → Self · *args: P.args (ParamSpec) · Unpack[Ts]
Self for fluent methods; ParamSpec/TypeVarTuple for decorators & variadic generics.

8Config & strictnesspyproject.toml

[tool.mypy] python_version = "3.12" strict = true★
Config in pyproject.toml (or mypy.ini). strict = true is the recommended target for new code.
disallow_untyped_defs = true warn_return_any = true warn_unused_ignores = true★
The high-value flags (all included in strict). Turn them on one at a time when adopting mypy on a legacy codebase.
[[tool.mypy.overrides]] module = "legacy.*" ignore_errors = true★
Per-module settings — relax rules for third-party or legacy modules while keeping your code strict.
ignore_missing_imports = true # for deps without type stubs
Silence "no stubs" errors for untyped libraries (or install a types-* stub package instead).

9Narrowing & ignoresescape hatches

if isinstance(x, str): ... # x is str in this block★
Type narrowing: isinstance, is None, assert, and truthiness checks refine a union to a specific type.
y = cast(int, get_value()) # trust me, it's an int
cast asserts a type without a runtime check — use when you know better than mypy. assert_type(x, int) to verify.
z = risky() # type: ignore[assignment]★
Suppress one line — always specify the error code in brackets so you don't hide new, unrelated errors.
from typing import TYPE_CHECKING if TYPE_CHECKING: from heavy import Thing★
Import types only for checking (avoids runtime import cost / cycles). Annotate with a string or under from __future__ import annotations.

!Common gotchasread before shipping

annotate empty containers
x = [] infers list[Any] forever. Write x: list[int] = [] so element checks actually happen.
Any is contagious & silent
A single Any disables checking downstream. Enable warn_return_any / disallow_any_* to catch it leaking in.
type: ignore without a code
A bare type: ignore masks all future errors on that line. Always use [error-code]; warn_unused_ignores flags stale ones.
runtime vs checker
mypy doesn't run your code — annotations aren't enforced at runtime. For runtime validation use Pydantic/typeguard, not mypy.
missing stubs ≠ your bug
"Cannot find implementation or library stub" means a dependency is untyped — install types-X or override the module, don't rewrite your code.

mypy cheat sheet