Skip to content

ty: Python Type Checker by Astral

by Tim Hopper
ty Type Checking

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?.

Key Features

  • Performance: significantly faster than mypy and pyright (roughly 7x faster than mypy on typical codebases). Fine-grained incremental analysis provides near-instant feedback in an IDE.
  • Diagnostics: Detailed error messages with code-span annotations and rich contextual information.
  • Language Server: Full LSP implementation with go-to-definition, go-to-declaration, go-to-type-definition, find references, completions with auto-import, rename refactoring, inlay hints, hover, signature help, quick fixes, semantic highlighting, and code folding.
  • Configurable Rules: Each diagnostic rule can be set to error, warn, or ignore. Supports per-file overrides and suppression comments.
  • Gradual Guarantee: Adding type annotations to working code never introduces new errors. Annotations only narrow existing errors, which makes incremental adoption predictable.
  • Advanced Type System: First-class intersection types, type narrowing (including hasattr narrowing), and reachability analysis based on type inference.
  • Notebook Support: Language server features for Jupyter notebooks with cross-cell analysis.

Type System Features

ty implements several type system features beyond what other type checkers provide:

  • Redeclarations: Allows reusing the same symbol with a different type within a function scope.
  • Intersection Types: First-class support for intersection types (A & B), which enables more precise type narrowing after isinstance checks.
  • Reachability Analysis: Uses type inference to detect unreachable branches, which can handle version-specific code paths for libraries like pydantic.
  • Fixpoint Iteration: Infers types for symbols that cyclically depend on themselves by iterating until the type converges.

Installation

The quickest way to run ty is with uvx:

uvx ty check

For project use, add ty as a development dependency:

uv add --dev ty
uv run ty check

ty can also be installed globally with uv tool install ty, via pip, pipx, or using standalone installers available for macOS, Linux, and Windows.

Basic Usage 

# Check the current project
ty check

# Check specific files
ty check src/main.py

# Check with a specific Python version target
ty check --python-version 3.12

# Get an explanation of a specific rule
ty explain rule <rule-name>

# Show all rules
ty explain rule

Configuration

ty reads configuration from pyproject.toml (under [tool.ty]) or a dedicated ty.toml file. Rule levels and other settings can be configured per-project:

[tool.ty.rules]
unused-ignore-comment = "warn"
possibly-missing-import = "error"

User-level configuration is also supported at ~/.config/ty/ty.toml.

Editor Integration

ty includes official editor support:

  • VS Code: Install the ty extension from the VS Code Marketplace.
  • Neovim: Configure via nvim-lspconfig or the built-in vim.lsp.config (Neovim 0.11+).
  • Zed: Built-in support (can be enabled in settings).
  • PyCharm: Native support starting with version 2025.3.
  • Emacs: Compatible via the built-in Eglot client (Emacs 29+).

For other editors, run ty server to start the language server.

Comparison to Other Tools

ty is not a drop-in replacement for mypy or pyright. It makes different design choices and has different default behaviors. The primary differentiators are speed (roughly 7x faster than mypy on typical codebases, with the gap varying by code patterns) and a gradual guarantee that adding annotations to working code never introduces new errors. ty checks all code by default, including unannotated function bodies that mypy skips, so a mypy-clean codebase can surface many new errors when first checked with ty. ty aims for conformance with the Python typing specification.

ty is in beta. Some features may be missing or behave differently compared to mature type checkers. Check the tracking issue for type system feature status.

Learn More

Last updated on
Twineuv