Skip to content

ty: Python Type Checker by OpenAI

by Tim Hopper · Markdown
ty Type Checking

ty (pronounced tee-why) is a static type checker and language server for Python from Astral, the creators of Ruff and uv, now part of OpenAI. 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 10x to 100x faster than mypy and Pyright on cold checks and pairs cleanly with Ruff and uv in the OpenAI 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 OpenAI-toolchain coherence is a priority. For a full comparison across all major type checkers, see How do Python type checkers compare?.

To get started, see How to try the ty type checker. If you’re already using mypy or pyright, see How to migrate from mypy to ty or How to migrate from pyright to ty.

Key Features

  • Performance: 10x to 100x faster than mypy and Pyright on cold checks (home-assistant: ty at 2.19s vs mypy at 45.66s). Fine-grained incremental analysis provides near-instant (sub-5ms) feedback in editor mode.
  • 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.

Pre-commit Integration

ty has an official pre-commit hook at astral-sh/ty-pre-commit, compatible with both pre-commit and prek:

repos:
  - repo: https://github.com/astral-sh/ty-pre-commit
    rev: v0.0.55
    hooks:
      - id: ty

The hook invokes ty through uv, making dependencies declared in pyproject.toml resolvable during the check. It runs against the whole project rather than only the staged files, since a change in one module can introduce type errors in another. The --isolated argument prevents the hook from creating or modifying a lockfile or virtual environment.

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 (10x to 100x faster than mypy and Pyright on cold checks, with home-assistant checking in 2.19s versus mypy’s 45.66s) 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