Python’s New Type Checker ty — Can It Dethrone mypy and pyright?

If you’ve been watching the Python tooling space, December 2025 brought something unexpected: ty, a new type checker from Astral — the same team behind uv and ruff. Within weeks of its beta release, the Python world started asking: is this the type checker that finally dethrones mypy and pyright?

In this tutorial, you will learn to:

• Understand what ty is, who built it, and why it matters for the Python ecosystem
• Compare ty, mypy, and pyright on speed, correctness, and ecosystem support
• Install and configure ty in a real Python project using uv or pip
• Run type checks, use watch mode, and set up LSP integration with Neovim or VS Code
• Diagnose and fix the five most common type errors ty flags

Prerequisites: Familiarity with Python type hints (e.g., Optional[int], Protocol) helps. If you are new to type annotations, read our Python Type Hints guide first. Python 3.12+ recommended.

The early numbers are striking. Astral claims ty runs 10–100× faster than mypy on large codebases. On Home Assistant’s codebase — over a million lines of Python — ty clocked ~2.19s versus pyright’s ~5.32s. That’s not a marginal improvement. That’s an order of magnitude shift.

In this guide, we’ll break down what ty is, how it stacks up against mypy and pyright, how to set it up in a real project, and whether you should switch now or wait for the stable release.

What is ty?

ty is an open-source Python type checker developed by Astral, the company behind ruff (the ultra-fast Python linter) and uv (the blazing-fast Python package manager). Astral has built a reputation for rewriting Python tools in Rust to achieve dramatic performance gains.

ty entered beta on December 16, 2025. Like ruff before it, ty is written in Rust and shares Astral’s philosophy: ship tools that are fast enough to run on every keystroke in your editor, without the performance penalty that has historically made type checking feel like a chore.

Key claim from Astral’s benchmarks: ty is 10–100× faster than mypy and pyright on large codebases, with fine-grained incremental analysis that makes editor feedback nearly instantaneous after the first run.

ty vs mypy vs pyright: The Core Comparison

Here’s how the three major type checkers stack up heading into 2026:

Feature	mypy	Pyright	ty (beta)
Language	Python	TypeScript	Rust
First release	2015	2019	Dec 2025
Speed (large codebase)	Slow (~10–60s)	Fast (~5s)	Fastest (~2s)
Incremental analysis	Partial	Yes	Fine-grained
Language Server (LSP)	No	Yes (pyright)	Yes
TypedPython support	Best	Good	Good (beta)
Plugin ecosystem	Yes (mypy extensions)	Yes (plugins)	Coming
Stable release	Yes	Yes	No (beta)

Benchmark data sourced from the pyrefly typing conformance comparison. Cold-run times on a standard project suite — your results will vary with project size and machine specs.

Speed: Where ty Wins

Astral’s own benchmarks on the Home Assistant codebase (a large, real-world Python project) show:

ty:        ~2.19s   (cold run, no cache)
Pyrefly:   ~4.81s   (incremental Rust checker)
Pyright:   ~5.32s
mypy:      ~10–60s  (varies by version/config)

The speed difference is most dramatic on cold runs. On incremental checks (after editing a single file), ty’s advantage compounds because its fine-grained incremental analysis only re-checks affected code — not the entire project.

Correctness: Where pyright Still Leads

Speed is one thing. Correctness is another. The Pyrefly team’s typing spec conformance analysis (March 2026) found that while ty and Pyrefly are both fast, pyright catches certain edge cases that ty currently ignores. In controlled tests, both ty and Pyrefly missed half a dozen issues that pyright caught.

ty is still in beta — some of these gaps will be closed before stable. But if you’re working with complex typing patterns (especially around generics and variance), pyright’s head start matters.

Ecosystem: Where mypy Still Dominates

mypy has the most mature plugin ecosystem, with first-party stubs for nearly every major Python library. It also has the longest track record — nearly a decade of production use at companies like Dropbox, Google, and Quora.

If you’re using mypy==1.0 extensions or rely on specific mypy plugins for frameworks like Django or Pydantic, you’ll have more friction switching to ty today.

Setting Up ty in a Real Python Project

Installing ty is trivial if you already use uv:

# Install ty (requires uv)
uv tool install ty

# Or via pip
pip install ty

# Verify
ty --version

Basic Configuration

ty uses pyproject.toml for configuration. Add a [tool.ty] section:

[tool.ty]
# Enable strict mode for maximum type safety
strict = true

# Target Python version
target-version = ["3.12"]

# Ignore specific files or directories
exclude = ["tests/fixtures/", "legacy/"]

# Enable/disable specific rule sets
enable = ["basic", "cast", "collection"]

Running Type Checks

# Check entire project
ty check

# Check specific files
ty check src/

# Watch mode (recheck on file changes)
ty check --watch

# JSON output for CI integration
ty check --output-format=json

Editor Integration

ty ships with a built-in language server, making it compatible with any editor that supports the Language Server Protocol (LSP) — VS Code, Neovim, Helix, and more.

# Start the language server
ty lsp

# For Neovim with nvim-lspconfig:
# Add to your init.lua or init.vim
require('lspconfig').ty.setup({})

For VS Code, install the ty extension from the Astral marketplace (or use the pre-release extension if the stable one isn’t published yet). Set "python.analysis.typeChecker": "ty" in your settings.

Example: Type Checking a Real Module

# src/models.py
from dataclasses import dataclass
from typing import Optional

@dataclass
class User:
    name: str
    email: str
    age: Optional[int] = None

    def greet(self) -> str:
        # ty verifies field types against their declarations
        # name: str is guaranteed — not affected by Optional age
        return f"Hello, {self.name}!"

    def years_until_century(self) -> Optional[int]:
        """Returns years until 100, or None if age unknown."""
        if self.age is None:
            return None
        return 100 - self.age

# src/api.py
from typing import Protocol

class UserRepository(Protocol):
    def get_user(self, user_id: int) -> Optional[User]: ...
    def save_user(self, user: User) -> bool: ...

def register_user(repo: UserRepository, name: str, email: str) -> User:
    user = User(name=name, email=email)
    repo.save_user(user)
    return user

Running ty check on this codebase gives instant feedback with rich contextual error messages — the kind pyright popularized, now at mypy-like speed.

Who Should Switch Now vs. Wait

Audience	Recommendation
New projects (Python 3.12+)	Try ty now — low legacy overhead, high payoff
Existing projects with pyright	Watch closely; pyright is still more complete
Enterprise/mypy-heavy projects	Wait for 1.0 stable; plugins may need updates
Library maintainers	Test ty against mypy now; report bugs to Astral
CI/CD pipelines (strict type checking)	Stick with pyright until ty matures

Common Errors and How to Fix Them

# Error 1: Implicit Optional (common in legacy code)
# mypy is stricter; ty may allow this
def get_user(id: int) -> dict:  # Should be Optional[dict]
    return {}

# Fix:
from typing import Optional
def get_user(id: int) -> Optional[dict]:
    return None  # or the actual dict

# Error 2: Type narrowing after mutable default
# ty catches this pattern better
def add_item(items: list[int] = []) -> list[int]:
    items.append(1)  # Mutable default! ty flags this
    return items

# Fix: use None instead
def add_item(items: Optional[list[int]] = None) -> list[int]:
    if items is None:
        items = []
    items.append(1)
    return items

Summary

• ty is Astral’s Rust-based type checker, beta released December 2025, part of the uv/ruff toolchain
• Speed: 10–100× faster than mypy, ~2× faster than pyright on cold runs (Home Assistant benchmark)
• Correctness: still catching up to pyright on complex typing patterns (in beta)
• Setup: uv tool install ty, configure in pyproject.toml, ships with built-in LSP
• Best for: new Python 3.12+ projects where you want fast feedback in editors
• Wait for stable if: you depend on mypy plugins, work with complex generics, or need maximum spec conformance

If you’re interested in Python tooling, also check out our Python Type Hints guide for more on Python typing, and stay tuned as we track ty’s stable release in 2026.