Python Type Checkers Cheatsheet: mypy, Pyright, ty, Pyrefly

For most of the last decade, choosing a Python type checker was a short conversation: mypy if you wanted the reference implementation, Pyright if you wanted speed and a good editor experience. That is no longer true. Two Rust-based checkers, Astral's ty and Meta's Pyrefly, both reached public beta at the end of 2025, and both are fast enough to change how you think about running a type checker on every keystroke.

More choice also means more confusion. The four tools read the same annotations but do not agree on everything: how much they infer, what they do with unannotated code, what their error codes are called, and how you silence them.

This post is a cheatsheet for picking one, configuring it, and running it in CI. Every output shown below comes from running the same file through the versions that were current on the date of this post. I avoid speed rankings from my own laptop; the numbers quoted are each project's own claims, and you should benchmark on your codebase.

1. The four checkers at a glance

A few points behind the table:

• mypy is still the reference. Many typing PEPs are prototyped there first, and its plugin system is a big reason many Django and Pydantic codebases stay on it. Version 1.18 shipped performance work that the release notes put at about 40% faster than 1.17 on mypy's own codebase.
• Pyright is the mature fast option. If you use VS Code with Pylance, you already run Pyright's engine. basedpyright is a community fork that adds stricter rules and baseline files; it tracks Pyright releases.
• ty and Pyrefly are betas. Their own announcements say so. Both are usable for editor feedback today; treat CI gating on them as an experiment you can back out of.

2. What actually differs

All four implement the same typing specification, so the differences show up at the edges. These are the ones that matter in practice.

The gradual typing philosophy differs, and that is what surprises people when they switch. mypy assumes that an unannotated function is code you have not opted into yet, so it stays quiet. Pyright, ty and Pyrefly check every function body by default. On a legacy codebase, that one difference can turn "0 errors" into several hundred.

3. Same file, four checkers

Here is a small file with three real bugs and one unannotated legacy function:

from dataclasses import dataclass


@dataclass
class User:
    id: int
    email: str | None = None


def domain(user: User) -> str:
    return user.email.split("@")[1]   # bug 1: email can be None


def total(prices: list[float]) -> int:
    return sum(prices)                 # bug 2: sum of floats is not an int


def legacy(x):
    return x + 1


legacy("a")                            # runtime TypeError, no annotations
count: int = "3"                       # bug 3: wrong type

All four checkers find the three annotated bugs with default settings. None of them flags legacy("a") by default, because x has no annotation. What changes is the wording and the error code:

Two details worth noticing. mypy blames the argument to sum, the others blame the return, which is the same bug seen from different ends. And ty's output is the most verbose by design: it prints the source with the declared type and the offending value both underlined, in a style borrowed from the Rust compiler.

What they infer without annotations

Inference is where the tools disagree the most. The same snippet run through each:

from typing import reveal_type


def legacy(x):
    return x + 1


def make():
    return [1, 2, 3]


reveal_type(legacy(1))
reveal_type(make())
items = []
items.append(1)
reveal_type(items)

Any and Unknown behave the same way for checking: anything goes. The practical consequence is that the same codebase gets more checking from Pyright and Pyrefly than from mypy or ty, because they know more types without you writing them. ty is still young here, so expect this row to change between releases.

4. Configuration side by side

All four can live in pyproject.toml. A realistic starting point for a project on Python 3.12 with a src/ layout and some legacy code:

# mypy
[tool.mypy]
python_version = "3.12"
files = ["src", "tests"]
strict = true
warn_unused_ignores = true

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

[[tool.mypy.overrides]]
module = ["some_untyped_lib.*"]
ignore_missing_imports = true

# Pyright
[tool.pyright]
include = ["src", "tests"]
exclude = ["src/myapp/legacy"]
pythonVersion = "3.12"
typeCheckingMode = "strict"
reportUnnecessaryTypeIgnoreComment = "warning"

# ty
[tool.ty.environment]
python-version = "3.12"

[tool.ty.src]
include = ["src", "tests"]

[tool.ty.rules]
possibly-unresolved-reference = "warn"
unused-type-ignore-comment = "error"

[[tool.ty.overrides]]
include = ["src/myapp/legacy/**"]

[tool.ty.overrides.rules]
all = "ignore"

# Pyrefly
[tool.pyrefly]
project-includes = ["src", "tests"]
project-excludes = ["src/myapp/legacy/**"]
python-version = "3.12"

[tool.pyrefly.errors]
bad-assignment = true
unused-ignore = "warn"
unannotated-parameter = "warn"

Things to know about each:

5. Suppressing errors

Suppressions are where switching tools gets expensive, because each tool's own comment means nothing to the others.

# Works in all four (PEP 484 standard comment)
value = load()  # type: ignore[assignment]

# Tool-specific, with rule names
user.email.split("@")  # pyright: ignore[reportOptionalMemberAccess]
user.email.split("@")  # ty: ignore[unresolved-attribute]
user.email.split("@")  # pyrefly: ignore[missing-attribute]

# Whole file
# pyrefly: ignore-errors

6. Running in CI

Pin the version. All four tools change their inference between releases, and an unpinned checker turns a dependency update into a red build nobody caused.

# .github/workflows/types.yml
name: types
on: [pull_request]

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync --locked
      # Pick one primary gate:
      - run: uv run mypy
      # - run: uv run pyright
      # - run: uvx [email protected] check --error-on-warning
      # - run: uvx [email protected] check

7. Speed: what the projects claim

Speed is the main reason people are looking at ty and Pyrefly, so here are the claims as each project published them. They are vendor benchmarks on vendor-chosen codebases.

On a small or medium codebase, all four are fast enough for CI. The gap matters most in the editor on very large monorepos, which is exactly the setting Meta and Astral built for. Measure on your own repository, with a warm and a cold cache, before using speed as the deciding factor.

8. Recent changes worth knowing

Only what shipped by early March 2026:

9. How to choose

A migration in five steps, whichever direction you go:

1. Run the new checker on a branch with no config and count errors by code. Most of the count usually comes from two or three codes.
2. Translate config deliberately, not field by field. Strictness levels do not map one to one. pyrefly init does a first pass for Pyrefly.
3. Freeze existing errors with a baseline (Pyrefly, basedpyright) or targeted type: ignore[...] comments, so the gate catches only new problems.
4. Run both checkers in CI for a while, the old one blocking, the new one advisory.
5. Flip the gate, remove the old tool, and clean up suppressions that only the old tool needed.

Why this matters

• Types are cheap checks that run before tests. All four tools caught all three annotated bugs in the sample with zero configuration.
• The defaults differ more than the engines. Unannotated code, inference and strictness explain most "it passes in one tool and fails in another" surprises.
• Speed changes how you use a checker. When diagnostics arrive in milliseconds, type checking moves from a CI step into the editing loop.
• Pin versions and prefer coded ignores. That keeps CI reproducible and keeps a future migration cheap.
• Betas are for trying, not yet for betting the gate on. Use ty and Pyrefly where a regression costs a little, and keep a stable checker where it costs a lot.

Final Thoughts

The Python type checking space has more serious options now than at any time since mypy started. That is good news: competition has already pushed mypy to get faster and is forcing everyone to be explicit about where they differ from the specification.

You do not need to pick a winner today. Keep the checker that gates your CI stable and pinned, try a new one in your editor for a week, and look at what it finds that the current one misses. That comparison on your own code is worth more than any benchmark table.

Sources

• mypy, Release notes (CHANGELOG) (September and November 2025): mypy 1.18 performance; mypy 1.19 Python 3.9 support ending, fixed-format cache, PEP 747 TypeForm.
• PyPI, mypy, pyright, ty, pyrefly release histories (accessed for versions up to March 2026): mypy 1.19.1 (December 15, 2025), Pyright 1.1.408 (January 8, 2026), ty 0.0.21 (March 6, 2026), Pyrefly 0.55.0 (March 3, 2026).
• mypy, The mypy configuration file: strict, overrides, warn_unused_ignores, check_untyped_defs.
• Microsoft, Pyright configuration: type checking modes and report* rules.
• Astral, ty: An extremely fast Python type checker and language server (December 2025): beta status, speed claims, language server features.
• Astral, ty configuration and suppression comments: config files and precedence, rule severities, overrides, ty: ignore and type: ignore behavior.
• Meta, Pyrefly Beta (November 2025): conformance from 39% to over 70%, performance, Django and Pydantic support, pyrefly init.
• Meta, Pyrefly configuration and error suppressions: project-includes, [errors], pyrefly: ignore, pyrefly suppress, baseline files.
• Python, Typing specification: type: ignore comments: the standard suppression comment all four tools read.