mypy
Optional static type checker for Python — verifies type annotations against usage to catch bugs before runtime. mypy features: PEP 484 type annotation checking, --strict for comprehensive type checking, --ignore-missing-imports for third-party stubs, reveal_type() for type inspection, cast() for type overrides, TypeVar for generics, Protocol for structural typing, TypedDict for typed dicts, overload for multiple signatures, Union/Optional/Literal types, mypy.ini/pyproject.toml configuration, incremental mode for speed, mypy daemon (dmypy) for watch mode, and stub files (.pyi) for typed third-party libraries.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Static type checker — no network calls, no code execution. mypy itself is safe. Type annotations improve security by making interfaces explicit — reduces type confusion bugs. Install only stub packages (types-*) from trusted sources as they affect type analysis.
⚡ Reliability
Best When
Large Python codebases requiring type safety — mypy catches entire classes of bugs at development time and serves as API documentation.
Avoid When
Runtime validation (use beartype/pydantic), style checking (use ruff), small scripts where annotation overhead exceeds benefit, or dynamically-typed code patterns.
Use Cases
- • Agent type check — mypy src/ — run mypy; agent checks entire src/ directory for type errors; exit code 0 for no errors; output: file.py:line: error: message [error-code]; errors like 'Argument 1 to ... has incompatible type str; expected int'
- • Agent strict mode — mypy --strict src/ — comprehensive; agent enables all strictness flags: --disallow-untyped-defs, --check-untyped-defs, --warn-return-any; strict mode catches most type issues; use for new projects; add gradually to existing code
- • Agent type inspection — x: int = 5; reveal_type(x) — mypy prints 'Revealed type is int'; agent discovers inferred types during development; reveal_type() is mypy-only (not runtime); remove from production code; useful for understanding complex type inference
- • Agent typed dict — from typing import TypedDict; class UserDict(TypedDict): id: int; name: str; email: str; def process(user: UserDict) -> str: return user['name'] — TypedDict; agent defines typed dict structure; mypy checks key access and value types; total=False for optional keys
- • Agent Protocol for duck typing — from typing import Protocol; class Drawable(Protocol): def draw(self) -> None: ...; def render(d: Drawable) -> None: d.draw() — structural typing; agent defines interface without inheritance; any class with draw() method is Drawable; mypy verifies structural compatibility
Not For
- • Runtime validation — mypy is static analysis only; type errors don't prevent runtime; for runtime type checking use beartype or pydantic
- • Linting style issues — mypy checks types not style; use ruff for style, unused imports, etc.
- • JavaScript/TypeScript — mypy is Python-only; for JS type checking use TypeScript
Interface
Authentication
No auth — static type checker.
Pricing
mypy is MIT licensed. Developed by Jukka Lehtosalo and Python community. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Missing stubs for third-party libraries — mypy raises error: 'Cannot find implementation or library stub for module named X'; install type stubs: pip install types-requests types-PyYAML; or: --ignore-missing-imports to suppress; agent code: add stub packages to dev dependencies; check typeshed for available stubs
- ⚠ Optional[X] is Union[X, None] — Optional[str] means str or None; mypy enforces None checks: if value is None: return; before using Optional value; agent code: any function accepting Optional must handle None; mypy catches: error: Item 'None' of 'Optional[str]' has no attribute 'upper'
- ⚠ # type: ignore suppresses specific errors — # type: ignore[arg-type] suppresses arg-type error on that line; bare # type: ignore suppresses all errors on line; agent code: use specific error codes: # type: ignore[union-attr]; avoid bare ignores; --warn-unused-ignores flags unnecessary ignores
- ⚠ reveal_type() must be removed before production — reveal_type(x) prints type during mypy analysis but causes NameError at runtime; agent code: use only during development; search-and-remove all reveal_type() calls before shipping; or wrap in TYPE_CHECKING block: from typing import TYPE_CHECKING; if TYPE_CHECKING: reveal_type(x)
- ⚠ Gradual typing with --ignore-missing-imports — fully untyped code: mypy --ignore-missing-imports --no-strict-optional for lenient mode; add stricter flags progressively; agent code adopting mypy: start with per-module ignore comments: # mypy: ignore-errors; gradually enable module by module with [mypy-module] settings in config
- ⚠ cast() bypasses type checking — from typing import cast; value = cast(str, get_value()) — tells mypy value is str; no runtime effect; agent code: use cast() sparingly for narrowing types when mypy cannot infer; overuse of cast() defeats purpose of type checking; prefer type guards: isinstance() checks for runtime narrowing
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for mypy.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.