ty's Breakthrough: Why Incremental Analysis Matters for Python

In a recent PyBytes podcast interview, Astral’s Charlie Marsh shared insights into what makes their new type checker ty unique and how it aims to address longstanding challenges in Python type checking.

What is ty?

ty serves dual purposes: it functions as a standalone command-line type checker (similar to mypy) and as a language server that powers IDE features like go-to-definition, code completion, and real-time diagnostics.

“We wanted to build a great type checker and a great language server, and they have things that are in common but they also have very different requirements,” Marsh explained. “If you don’t think about both of those from the start, you end up in a little bit of trouble.”

Incrementality at the core

The most significant technical innovation in ty is its incremental analysis system. Unlike traditional type checkers that reanalyze entire codebases when files change, ty tracks dependencies between code elements and only recomputes what’s actually affected by changes.

“If we already understand the state of the program and you change something that doesn’t affect what you’re looking at, we should only have to redo work that is impacted by what you change,” Marsh noted. “It’s not like we have to run mypy over your full codebase every single time you change a file.”

This incrementality operates at multiple levels, from file-level changes down to function-level modifications. When you modify a function’s local annotation, ty only needs to recompute that specific function rather than analyzing the entire project.

To achieve this, Astral built ty on top of Salsa, a Rust framework also used by rust-analyzer (Rust’s primary language server). This choice required significant investment; the Astral team dedicates one person full-time to contributing to Salsa and adapting it for Python’s unique requirements.

Exceptional diagnostics

Beyond performance, ty prioritizes delivering helpful, contextual error messages. The diagnostic system can display information from multiple files simultaneously, showing both function calls and their definitions in error reports.

“Our goal is to build kind of this really rich system to give you really helpful error messages and pull in really important context,” Marsh explained. The team draws inspiration from Rust’s compiler, which is renowned for its informative error messages.

ty goes further by explaining not just what’s wrong, but why the type checker made certain inferences. For example, if you try to import a Python 3.13-only module while targeting Python 3.10, ty shows you exactly where you specified the minimum Python version and suggests how to fix it.

Accelerating AIs

These rich diagnostics serve a dual purpose: they help human developers and provide better feedback loops for AI coding assistants. “If you’re running an agent, like if you’re using Claude Code or something similar, the thing that really matters is you have to create a good feedback loop,” Marsh noted. Better error messages help AI models understand problems and generate appropriate fixes.

Gradual adoption philosophy

ty takes a different approach to type checking untyped code, implementing what’s called the “gradual guarantee.” Rather than making assumptions that generate false positives, ty avoids forcing developers to add annotations just to silence incorrect warnings.

“We try to minimize false positives, especially on untyped code,” Marsh explained. “The goal is to minimize the kind of false positives that lead to fighting the type checker, especially on untyped code.”

For example, when encountering x = 1 without type annotations, other type checkers assume x can only be an integer. ty treats it as potentially integer or unknown, avoiding false positives if you later assign None to x.

Current status and future plans

ty is currently in pre-alpha, marketed as “not ready for production.” However, some teams are already using it successfully. The tool doesn’t yet support all Python typing features, but the foundation is solid.

The team targets a beta release later in 2025, at which point most teams should be able to migrate from existing type checkers. This beta will mark ty’s transition from experimental tool to production-ready alternative.

Integration with ruff

ty shares infrastructure with ruff, including the parser and AST representation. This shared foundation enables potential future integration such as enabling more sophisticated linting rules in ruff. “Ultimately, we don’t just want to be able to build a type checker, we want to be able to build a type-aware linter,” Marsh revealed.

Getting started

For developers interested in trying ty, installation is straightforward:

uvx ty check .

The ty VS Code extension provides language server functionality for those wanting to experience the IDE integration.