Python Developer Tooling Handbook – ty

ty: A Complete Guide to Python's Fastest Type Checker

Tim Hopper — Fri, 15 May 2026 11:47:17 -0400

ty is a Python type checker and language server built by Astral, the team behind Ruff and uv. It checks Python code for type errors an order of magnitude faster than mypy. The same binary that runs ty check in CI also serves as a full language server, powering editor features like completions and go-to-definition.

Why ty exists

ty’s gradual guarantee makes incremental type adoption safe: adding annotations to your code will never introduce new errors. You can annotate a function’s return type and ty won’t flag callers that were already passing the wrong type just because the annotation appeared. Each annotation only narrows existing errors rather than creating new ones.

How do Python type checkers compare?

Tim Hopper — Fri, 15 May 2026 22:53:52 -0400

mypy, pyright, ty, Pyrefly, Basedpyright, and Zuban all analyze type annotations to catch bugs before runtime. They read the same type-hint annotations (from PEP 484, the standard that introduced Python’s type system in 2014) and largely agree on the parts of the spec a working program uses. They disagree on speed, default strictness, treatment of unannotated code, editor integration, and licensing, and those disagreements are what make the choice matter.

The handbook recommends Pyrefly (Meta) as the default for new projects. See When to choose each for the rationale and the cases where a different checker fits better.

How to install the Astral plugins for Claude Code

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

Astral publishes an official Claude Code plugin that bundles three skills (/astral:uv, /astral:ruff, /astral:ty) and a ty language server. The skills give Claude up-to-date usage guidance for each tool, and the language server feeds live type-checking diagnostics into the conversation.

Prerequisites

Claude Code installed
uv installed (required by the ty language server)

Install the plugin for yourself

1. Add the Astral marketplace

Run this slash command inside Claude Code:

How to migrate from mypy to ty

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

ty is a fast Python type checker, developed by Astral (the creators of uv and Ruff). It runs faster than mypy, especially on large codebases.

ty is currently in beta. While actively developed, it’s still missing some features and may not be ready for full production adoption. This guide helps evaluate readiness and plan for migration.

Understanding ty

When to consider migrating

Projects needing faster type checking on large codebases
Teams already using other Astral tools (Ruff, uv)
Projects not relying on mypy plugins

When to wait

Projects requiring Pydantic, Django, or SQLAlchemy mypy plugins
Projects requiring mature, battle-tested tooling

Installation and basic usage

Installing ty

ty is distributed as a standalone binary. The easiest way to use it is via uvx:

How to migrate from pyright to ty

Tim Hopper — Mon, 18 May 2026 09:56:08 -0400

ty is a Python type checker developed by Astral (the creators of uv and Ruff). It ships as a single binary with no runtime dependencies, which eliminates pyright’s Node.js requirement.

ty is currently in beta. While actively developed, it’s still missing some features and may not be ready for full production adoption. This guide helps evaluate readiness and plan for migration.

Installation and basic usage

Installing ty

ty is distributed as a standalone binary. The easiest way to use it is via uvx:

How to try the ty type checker

Tim Hopper — Sat, 16 May 2026 06:16:22 -0400

This guide shows you how to try out ty, a static type checker and language server, in your project.

Looking to migrate from mypy to ty? See How to migrate from mypy to ty for detailed guidance.

Prerequisites

To proceed, you’ll need uv.

How to use ty in CI

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

ty can run in CI with no installation step beyond uv. Because ty is a single binary with no runtime dependencies, it adds minimal overhead to your pipeline.

GitHub Actions

The simplest approach uses uvx to run ty without adding it as a project dependency:

- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v7
- run: uvx ty check src/

To get inline annotations on pull requests, use the github output format:

ty: Python Type Checker by Astral

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

ty (pronounced tee-why) is a static type checker and language server for Python from Astral (creators of Ruff and uv). It performs static analysis on Python code to identify type-related issues before runtime.

ty was initially known by the code name “Red-Knot” during its early development phase. The tool is in beta, with a stable 1.0 release targeted for 2026.

When to use ty

ty is an alternative to the handbook’s recommended type checker, Pyrefly. Its “gradual guarantee” ensures that adding type annotations to working code never introduces new errors, which makes incremental adoption predictable in a partially-typed codebase. ty also runs 10-100x faster than mypy and pyright and pairs cleanly with Ruff and uv in the Astral toolchain. Pyrefly is recommended over ty for most new projects because ty is still in beta as of 2026 and its typing-spec conformance trails Pyrefly’s; choose ty if the gradual guarantee matters more than feature completeness, or if Astral-toolchain coherence is a priority. For a full comparison across all major type checkers, see How do Python type checkers compare?.