Written for Python 3.14 and 3.15, mypy 2.4.1, Pyright 1.1.414, Pyrefly 1.4.1 and ty 0.0.106, current as of November 18, 2026.
A type hint is an annotation such as def total(invoice: Invoice) -> int that records what a function accepts and returns, as defined in PEP 484. Python ignores it at runtime, and a separate Python type checker such as mypy or Pyright reads the hints and reports code that breaks them.
On a Thursday afternoon, someone changes parse_amount() in a shared money module to return a Decimal instead of an int. The repo’s own tests pass. By Monday, a payouts worker and an invoicing service are both rounding cents differently, and the bug report reads like a finance problem. A type checker in CI would have flagged both callers in the pull request. The catch on a 300,000-line repository is that the first full run prints thousands of errors, and a team that tries to fix them all at once stops shipping features.
For most teams, the plan is to pick mypy or Pyright as the single CI gate, start on one widely imported package, ignore the rest per module, and block new errors from day one. Each package then tightens toward strict mode as it’s finished, and the checker’s scope grows every sprint.
Python type checkers and typing at a glance
Type hints are optional annotations that a separate checker reads, and the interpreter doesn’t enforce them. The table shows where the language and the four main checkers stand in November 2026.
| Item | Status in November 2026 | Source |
|---|---|---|
| Latest Python | 3.15.0, released October 9, 2026 | What’s New in Python 3.15 |
| Annotation evaluation | Deferred by default since 3.14 (PEP 649 and PEP 749) | What’s New in Python 3.14 |
| from __future__ import annotations | Deprecated, behavior unchanged in 3.14, removal after 3.13’s end of life in 2029 | 3.14 porting notes |
| Python 3.10 | End of life on October 1, 2026 (passed) | Python devguide |
| mypy | 2.4.1, released October 28, 2026 | mypy changelog, PyPI |
| mypy parallel checking | Up to 5x faster with 8 workers; stable since 2.4 | mypy changelog |
| Pyright | 1.1.414, default mode “standard” | Pyright configuration, release tag |
| Pyrefly | 1.4.1, stable since 1.0 on May 12, 2026 | Pyrefly v1.0 announcement, PyPI |
| ty | 0.0.106, still beta | ty on PyPI, ty beta announcement |
What gradual typing means for a large codebase
Gradual typing means annotated and unannotated code live in the same repository, and you add type hints one module at a time. The main lever is how your checker treats code nobody has annotated yet.
mypy’s common issues page says functions with no annotations at all “are not type-checked,” so a first run reports far less than the codebase contains. Pyright takes the other approach. Pyright’s mypy comparison says it checks all code by default and infers the return types of unannotated functions.
Where type hints pay off first
Type hints on shared code pay off first: function signatures, collection types, and data shapes that other modules import. Those annotations tell every caller what goes in and what comes out, and the checker flags a broken contract before it reaches another service.
The payoff drops sharply for private helpers deep inside one module. mypy’s guide to existing codebases recommends annotating widely imported modules, such as utilities and model classes, early, because many files depend on one definition.
What type hints don’t do
Type hints don’t run any checks at runtime. A function annotated to return int can still return a string if nothing runs the checker.
- Any switches checking off. Every value typed as Any, and everything it flows into, goes unchecked.
- A passing checker doesn’t prove the code is correct. It proves the annotations agree with each other.
- Unannotated code is a blind spot in mypy until you turn on check_untyped_defs.
How to choose a Python type checker
mypy or Pyright fits the CI gate for most repositories today. Pyrefly and ty are worth piloting for editor speed, or when CI check time still misses your budget after you’ve timed mypy’s parallel mode. The table compares what each project documents.
| Checker | Maintainer | Status and version | Behavior to know on day one | Best fit |
|---|---|---|---|---|
| mypy | Python project | Stable, 2.4.1 | Skips unannotated function bodies by default; parallel workers with -n auto | Per-module config for staged rollouts |
| Pyright | Microsoft | Stable, 1.1.414 | Checks everything and infers return types | Strict paths, per-file comments, editor use |
| Pyrefly | Meta | Stable, 1.4.1 | Reads an existing mypy or Pyright config | Migration, with pyrefly infer drafting annotations |
| ty | Astral | Beta, 0.0.106 | Rust-based checker and language server | A pilot alongside your main gate |
How mypy and Pyright differ on day one
The main difference in mypy vs Pyright is how each handles unannotated code. Pyright reports more on day one and, per its comparison page, narrows a variable’s type on assignment even when the variable has a declared type. mypy gives you a smaller first report with finer per-module control through [[tool.mypy.overrides]] sections.
Check time used to be the other argument. Since mypy 2.0, –num-workers runs the check in parallel, and the release notes report “up to 5x” faster runs on large projects with 8 worker processes. Treat that as the maintainers’ best case and time it on your own repository.
If your rollout plan leans on per-module ignores, mypy fits. If your team works in VS Code and wants the editor and CI to agree, Pyright fits.
Running two checkers
Pick one checker as the CI gate and treat the other as an editor aid. Checkers sometimes disagree because their defaults and inference differ. The shared typing specification and a conformance test suite exist to shrink those gaps, but they don’t remove them.
When a developer’s editor uses Pyright and CI uses mypy, resolve each mismatch in favor of the CI gate.
How to evaluate Pyrefly and ty on your repository
Pyrefly reached stable 1.0 on May 12, 2026. Per the Pyrefly v1.0 announcement, it reads an existing mypy or Pyright configuration, pyrefly init writes a pyrefly.toml or updates pyproject.toml, project_excludes skips legacy code, and pyrefly infer drafts annotations you then review. Run against a project with only a [tool.mypy] section, Pyrefly 1.4.1 picked it up with no extra setup.
ty is still beta. Astral announced the beta on December 16, 2025, and recommends it “to motivated users for production use.” Both Rust-based checkers are built for speed and editor responsiveness, so time them against mypy’s parallel mode on your code before you trust any vendor number:
- Pin each candidate’s version, mypy included.
- Time mypy -n auto on the package as your baseline.
- Run each candidate on the same package.
- Count errors by error code and read a sample of each.
- Time a full run and an edit-then-check cycle.
- Confirm it supports per-package strictness the way your plan needs.
Adding type hints to an existing codebase, package by package
Roll out type checking one package at a time: get the checker passing on a small scope, block new errors in CI, and widen the scope each sprint. This follows mypy’s guide to existing codebases, and the same shape works for Pyright.
- Pick one checker and pin it. Check it in the config so every laptop and CI runner gets the same result.
- Start on one widely imported package, such as shared_utils or your data models. Annotations there improve inference everywhere it’s used.
- Get the checker passing. Set ignore_errors = true per module for everything you aren’t ready to check. For untyped dependencies, install stubs first and fall back to per-module ignore_missing_imports = true. Avoid global ignores, and treat follow_imports changes as a last resort, as the mypy guide advises.
- Block new errors in CI as soon as the baseline passes. A baseline anyone can break without a failing build doesn’t hold.
- Turn on check_untyped_defs. mypy then reads the bodies of unannotated functions and treats their arguments and return values as Any, which catches wrong attribute names and bad calls in old code without anyone writing an annotation. The mypy guide recommends enabling it “as soon as you can.”
- Annotate the most-imported modules.
- Require annotations on finished packages with disallow_untyped_defs = true per module in mypy, or by adding the path to Pyright’s strict list.
- Clear dead suppressions with warn_unused_ignores in mypy or reportUnnecessaryTypeIgnoreComment in Pyright (off by default, per the Pyright configuration docs).
- Move finished packages to strict mode.
pip install "mypy==2.4.1"
mypy -n auto src/shared_utils
[tool.mypy]
check_untyped_defs = true
warn_unused_ignores = true
num_workers = "auto"
[[tool.mypy.overrides]]
module = ["legacy_billing.*"]
ignore_errors = true
[[tool.mypy.overrides]]
module = ["shared_utils.*"]
disallow_untyped_defs = true
[[tool.mypy.overrides]]
module = ["vendor_sdk.*"]
ignore_missing_imports = true
With that config, mypy 2.4.1 stays silent on legacy_billing but flags this unannotated function elsewhere in the repo, because check_untyped_defs reads its body:
def report(rows):
total = 0
for r in rows:
total += r.amount
return total.upper() # mypy: "int" has no attribute "upper" [attr-defined]
In Pyright, a path in the strict list gets the same treatment as a # pyright: strict comment at the top of each file in it, per Pyright’s configuration docs.
[tool.pyright]
typeCheckingMode = "standard"
strict = ["src/shared_utils"]
On large repositories, turn on mypy’s parallel checking with -n auto or num_workers = “auto”, which picks a worker count from your CPU cores and caps it at 8, per the 2.4 release notes. The mypy daemon covers fast incremental runs on a laptop, and the existing-codebase guide suggests remote caching for projects of “at least 100,000 lines of code or so.” Run the checker the same way everywhere: put the command in a Makefile target or pre-commit hook and have CI call that exact target.
make typecheck # runs: mypy -n auto src
mypy’s strict = true turns on a set of flags that includes disallow_untyped_defs, disallow_any_generics, warn_return_any, no_implicit_reexport and strict_equality (the full list is in the mypy command line docs). Before you move a package to strict mode, run this go/no-go list:
- The package passes with check_untyped_defs and disallow_untyped_defs.
- Every ignore comment carries an error code.
- warn_unused_ignores reports nothing.
- Public functions return concrete types, with no bare Any.
- The owning team agrees to keep it strict.
Track counts you can act on: errors by error code per package, ignore comments per package, and how many packages still sit under ignore_errors.
Upgrading from mypy 1.x to 2.x
Run the upgrade on a branch and expect new errors in code that passed under 1.x. A team jumping from 1.20 to 2.4.1 crosses five releases, and the defaults changed in two of them. The mypy blog has a post for each release.
| Release | Released | What changes for a team coming from 1.x |
|---|---|---|
| 2.0 | May 6, 2026 | –local-partial-types and –strict-bytes on by default; –allow-redefinition takes the newer, more flexible behavior; –python-version 3.9 no longer supported; –ignore-missing-imports now respected for every package; experimental parallel checking, up to 5x faster with 8 workers |
| 2.1 | May 11, 2026 | No option or default changes; –num-workers can be set from an environment variable; TypeForm support was pulled back over a performance regression |
| 2.2 | July 7, 2026 | Closed TypedDicts (PEP 728); complete type parameter defaults (PEP 696); explicit __new__() return types now respected, which can change inferred types; TypeForm support no longer experimental |
| 2.3 | July 13, 2026 | Announces the switch to the native parser and asks teams to test –native-parser |
| 2.4 | October 1, 2026 (2.4.1 on October 28) | Native parser on by default (–no-native-parser falls back, legacy parser removal planned for early 2027); type comments on for and with statements now ignored; parallel checking stable, with -n auto; Python 3.15 support |
Source: mypy changelog and the mypy 2.0 release post.
–strict-bytes is the change most likely to light up an old codebase. Following PEP 688, mypy 2.x no longer treats bytearray or memoryview as assignable to bytes. The first call below passes on mypy 1.20.2 and fails on 2.4.1:
def checksum(data: bytes) -> int:
return sum(data) % 256
checksum(bytearray(b"payload")) # mypy 2.x: incompatible type "bytearray" [arg-type]
def normalize(data: bytes | bytearray) -> int: # widen the signature instead
return sum(data) % 256
–local-partial-types changes how mypy infers a variable assigned None in one scope and a real value in another, such as a module-level cache filled inside a function. The changelog says turning it off still works for now but will be removed, so annotate those variables rather than pinning the old flag.
Changes in Python 3.14 and 3.15 that affect typed code
Two Python releases changed how typed code behaves in the past year. Your oldest supported Python version decides which syntax you can use.
Python 3.10 reached end of life on October 1, 2026, so 3.11 is now the oldest release still getting security fixes, and mypy 2.x can no longer target 3.9 at all. The samples in this article assume Python 3.12 or newer for the PEP 695 type parameter syntax, and Python 3.14 to run exactly as written. If the same upgrade also puts the free-threaded build on the table, that is a concurrency decision with its own trade-offs, covered in our guide to the Python GIL and free-threading; it doesn’t change how annotations behave.
Deferred annotations in 3.14
In 3.14, annotations on functions, classes, and modules are evaluated only when needed, so forward references no longer need quotes. Code that reads __annotations__ directly should move to annotationlib.get_annotations(). The upgrade details, including the three annotation formats, sit in our article on what’s new in Python 3.14, so this section stays on what it means for a checker rollout.
The future of from __future__ import annotations
The import is deprecated, but its behavior is unchanged in 3.14, and nothing warns about it yet. The 3.14 porting notes say removal waits until after Python 3.13’s end of life in 2029, and PEP 749 says the DeprecationWarning starts no sooner than the first release after that date. The import itself came from PEP 563, which PEP 649 has superseded.
Keep the import while you support versions before 3.14. Drop it once your floor is 3.14, after checking libraries that read annotations at runtime. typing_extensions backports Format and get_annotations for cross-version code.
New in 3.15: TypeForm and closed TypedDicts
Python 3.15 shipped on October 9, 2026 with TypeForm (PEP 747) for values that are themselves type expressions, and closed TypedDicts (PEP 728). Both are listed under new typing features in What’s New in Python 3.15, and the typing docs mark TypeForm as added in 3.15. A closed TypedDict rejects keys beyond the declared ones.
# Requires Python 3.15
from typing import TypedDict, TypeForm
class Settings(TypedDict, closed=True):
host: str
port: int
def describe(tp: TypeForm[object]) -> str:
return repr(tp)
bad: Settings = {"host": "db", "port": 5432, "debug": True} # rejected: extra key
mypy 2.4 supports closed TypedDicts and TypeForm, but not the extra_items argument from PEP 728 yet. Pyright 1.1.414, Pyrefly 1.4.1 and ty 0.0.106 also reject the extra key in this sample. mypy 2.4 also type checks 3.15’s built-in sentinel and lazy imports, per its changelog.
Deprecated typing patterns to clean up
Several typing names are deprecated, and two have removal dates. None of these removals have happened as of November 2026, per the typing module’s deprecation timeline.
| Pattern | Deprecated in | Removal | Replace with |
|---|---|---|---|
| typing.List, typing.Dict, typing.Type and other collection aliases (PEP 585) | 3.9 | Undecided | list, dict, type |
| typing.Optional and typing.Union in new code | Not deprecated | None planned | X \| None and X \| Y (PEP 604, style only) |
| typing.ByteString | 3.9 | 3.17 | collections.abc.Buffer or bytes \| bytearray |
| typing.AnyStr | 3.13 | 3.18 | Type parameter syntax |
| typing.TypeAlias | 3.12 | Undecided | The type statement |
| typing.Text | 3.11 | Undecided | str |
Python 3.15 already removed the keyword-argument NamedTuple form (NamedTuple(“Point”, x=int, y=int)) and TypedDict(“TD”) with no fields, per What’s New in Python 3.15. In 3.15, importing typing.ByteString also emits a DeprecationWarning.
For narrowing functions on 3.13 and newer, the typing docs say TypeIs (PEP 742) “usually has more intuitive behavior than TypeGuard,” with exceptions they list.
Type hint patterns teams use most
The patterns below cover most of what a team annotates day to day. Each sample runs on Python 3.14 and passes mypy 2.4.1 and Pyright 1.1.414.
Functions, defaults, and collections
Annotate every parameter and the return type. Use built-in generics like list[int] and dict[str, int], and abstract types like Sequence or Mapping for parameters you only read.
from collections.abc import Mapping, Sequence
def chunk(items: Sequence[int], size: int = 100) -> list[tuple[int, ...]]:
return [tuple(items[i : i + size]) for i in range(0, len(items), size)]
def lookup(table: Mapping[str, int], key: str, default: int | None = None) -> int | None:
return table.get(key, default)
seen: set[str] = set()
Tuples are the exception among containers. tuple[int, str] describes a fixed-length pair, and tuple[int, …] describes any length. A default of None needs | None in the annotation, or the checker rejects it.
Unions, Literal, and Any
Use a union (int | str) when a value can be one of a few types, and X | None when it can be missing. Use Literal when only a few exact values are valid, such as environment names. The checker then rejects “prd” as a typo.
import json
from typing import Any, Literal
type Env = Literal["dev", "staging", "prod"]
def connect(env: Env, timeout: float | None = None) -> str:
return f"{env}:{timeout or 30}"
def parse_legacy(raw: str) -> dict[str, Any]:
data: dict[str, Any] = json.loads(raw)
return data
Keep Any for true boundaries: raw JSON, untyped third-party calls, or legacy code you haven’t reached yet. Treat each one as a known gap you plan to close.
Structured data and interfaces
Pick the shape that matches how the data moves:
- TypedDict for dictionaries that cross a boundary, such as JSON payloads and config.
- NamedTuple for small immutable records.
- NewType for IDs that share a base type but shouldn’t mix, like UserId and OrderId.
- The type statement to name a long type.
- Protocol for structural interfaces between modules, so callers depend on methods instead of importing a concrete class.
- Type parameter syntax for generic helpers.
from typing import NamedTuple, NewType, Protocol, TypedDict
UserId = NewType("UserId", int)
class OrderPayload(TypedDict):
order_id: str
amount_cents: int
note: str | None
class Point(NamedTuple):
x: float
y: float
class Notifier(Protocol):
def send(self, user: UserId, message: str) -> None: ...
def first[T](items: list[T]) -> T:
return items[0]
A type alias makes two types equivalent. NewType works differently: the checker treats UserId as a subclass of int, so a plain int can’t go where a UserId is expected.
Callbacks, decorators, and generators
Use Callable[[Arg], Return] for simple callbacks and a Protocol with __call__ for keyword-only or variadic signatures. For decorators, a ParamSpec (**P in type parameter syntax) keeps the wrapped function’s parameters intact.
import functools
from collections.abc import AsyncIterator, Callable, Generator
def logged[**P, R](func: Callable[P, R]) -> Callable[P, R]:
@functools.wraps(func)
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
print(f"calling {func.__name__}")
return func(*args, **kwargs)
return wrapper
def countdown(n: int) -> Generator[int, None, str]:
while n > 0:
yield n
n -= 1
return "done"
async def stream(n: int) -> AsyncIterator[int]:
for i in range(n):
yield i
Generator[Yield, Send, Return] covers full generators, and Iterator[int] is enough when a generator only yields. A callback that returns a coroutine is Callable[…, Awaitable[T]].
Third-party types and circular imports
A package that ships its own type hints includes a py.typed marker file, and stub-only packages are named foopkg-stubs. Per the typing spec’s distribution rules (which grew out of PEP 561), checkers look at your code, then standard library stubs from typeshed, then stub packages, then installed packages with py.typed.
Look for one of those before adding ignore_missing_imports, and add py.typed to your own internal packages so other teams’ checkers see their types.
Typing often exposes circular imports. Put type-only imports under TYPE_CHECKING. On 3.14 the annotation below is never evaluated at import time; on older versions, quote it or use the future import.
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from billing.invoices import Invoice
def total(invoice: Invoice) -> int:
return invoice.amount_cents
Rules for ignores and Any
Require error codes on suppressions (# type: ignore[arg-type] or # pyright: ignore[reportArgumentType]). Pyright’s comment docs say a # pyright: ignore[rule] comment suppresses only the named rules on that line. Watch for Any at module boundaries, because one untyped return spreads into every caller.
Typing in code review
Gradual typing holds when type checks are part of every pull request. In code review, apply these rules:
- Treat a changed signature in a shared module as an API change, with the same care as a renamed endpoint.
- Ask for a reason on every new ignore comment.
- Use @override (PEP 698) on subclass methods so a rename in the base class surfaces as an error.
- Reject new Any at module boundaries without a follow-up ticket.
Type hints also give AI coding assistants and reviewers explicit contracts to check generated code against. A type checker in CI catches some mistakes in generated code before a person reviews it.
Skills to look for in a typing rollout team
A typing rollout needs people who can write precise annotations for generics, protocols, and overloads; configure a checker per module; wire it into CI; and judge when a package is ready for strict mode. If you’re writing the role, start from Arc’s Python developer job description template, and check the Python developer hourly rates before you set a budget for a contractor-led rollout.
Typing questions make a strong senior interview signal. A good exercise hands the candidate a 50-line module with three # type: ignore comments and asks which ones they would remove and how. Arc’s software engineer interview questions give you a base to adapt, and the remote technical interview guide covers running that exercise over a shared screen.
The same skills matter for service teams. Look for them when you hire back-end developers for typed APIs and workers. Django codebases add their own typing work around models and querysets, which is worth testing for when you hire Django developers. When you compare hiring routes, the best platforms to hire Python developers lists what each offers.
Frequently asked questions
Do Python type hints affect runtime performance?
No: Python doesn’t enforce type hints at runtime, and a separate type checker reads them. Since Python 3.14, annotations are evaluated only when something asks for them (PEP 649), which keeps the cost of defining them low. Code that does read annotations, such as a validation or serialization library, pays for evaluating them when it asks.
Which Python type checker should I use?
Use mypy 2.4.1 or Pyright 1.1.414 for the CI gate in most teams today. mypy suits staged, per-module rollouts and now checks in parallel, and Pyright suits teams that want strict paths and strong editor support. Pyrefly has been stable since 1.0 in May 2026, and ty is still beta, so pilot either one on a branch first.
What changed in mypy 2.0?
mypy 2.0, released May 6, 2026, turned on local partial types and strict bytes by default, dropped Python 3.9 as a target, and added experimental parallel checking that the release notes put at up to 5x faster with 8 workers. Later 2.x releases made the native parser the default and parallel checking stable, so upgrade on a branch.
Should I still use the future import for annotations?
Keep it only if you support Python versions before 3.14. The import is deprecated; its behavior is unchanged in 3.14, and removal comes after Python 3.13’s end of life in 2029. Once your floor is 3.14, you can remove it, after confirming any library that reads annotations at runtime handles deferred evaluation.
How do I add type hints to an existing Python project?
Start on one widely imported package and set per-module ignore_errors for the rest. Pin the checker version, block new errors in CI, and turn on check_untyped_defs. As each package gets annotated, add disallow_untyped_defs for it, then move it to strict mode once it passes cleanly and its ignores carry error codes.
Are typing.List and typing.Optional deprecated?
typing.List and the other collection aliases have been deprecated since Python 3.9, with removal undecided, so write the built-in list and dict generics instead. typing.Optional isn’t deprecated. The X or None union syntax is the modern form, so use it in new code and leave existing Optional uses for a cleanup pass.
Choosing a checker and a rollout pace
Pick mypy or Pyright as the gate, stage strictness per package in checked-in config, and block new errors from day one. Turn on check_untyped_defs early, because it finds real bugs in old code before anyone writes an annotation. If you’re on mypy 1.x, upgrade on a branch and time mypy -n auto before deciding check time is a reason to switch; pilot Pyrefly or ty when editor speed matters or when the parallel run still misses your CI budget.
A rollout like this goes faster with an engineer who has done it before. Arc matches you with top 2% vetted Python developers who configure checkers per module and fix the cause of an error instead of adding an ignore. Freelancers can start within 72 hours and full-time hires within 14 days, and you pay $0 until you hire.








