Ty 0 0 33

ty 0.0.33

Overview

ty is an extremely fast Python type checker written in Rust by Astral (the same team behind Ruff and uv). It is 10x-100x faster than mypy and Pyright while providing comprehensive diagnostics, configurable rule levels, and advanced type system features including intersection types, redeclarations, and gradual type support.

ty supports all typing features described in the Python typing specification. Beyond standard type checking, ty provides a full-featured language server for IDE integration with diagnostics, code completions, go-to-definition, hover information, inlay hints, rename refactoring, and more.

Key capabilities:

• Blazing fast: Written in Rust with parallel analysis and fine-grained incrementality
• Type system: Intersection types (A & B), redeclarations, gradual guarantee, fixpoint iteration
• Configuration: pyproject.toml ([tool.ty]) or standalone ty.toml, with per-file overrides
• Language server: Full LSP support for VS Code, Neovim, Zed, PyCharm (2025.3+), Emacs, and any LSP-compatible editor
• Watch mode: Incremental rechecking on file changes with fine-grained dependency tracking
• Python versions: Supports targeting Python 3.7 through 3.15

Notable changes in 0.0.30–0.0.33

• v0.0.33: Prefers declared type of annotated assignments when inferred and declared types are mutually assignable (reduces false negatives with Unknown). Improved diagnostics with error context for assignability, TypedDict, intersection types, return/yield, and attribute assignment. LSP gains keyword argument inlay hint "baking" and go-to-definition for literal enum member hints.
• v0.0.32: No longer unions Unknown into most inferred types of unannotated attributes (may produce new diagnostics on upgrade). LSP dims unreachable code. Performance: memoized binary operator return types, protocol compatibility gated on member count.
• v0.0.31: Added --fix mode for auto-fixing diagnostics. Improved TypedDict and NamedTuple handling (inherited field conflicts, duplicate keyword errors, subclass shadowing). Reduced memory usage for large dataclasses.
• v0.0.30: Fixed stack overflows from recursive types, improved Callable rendering, nested TYPE_CHECKING block inheritance, and ParamSpec/Concatenate handling.

When to Use

• Type checking Python codebases with fast feedback (CI/CD, pre-commit, or interactive)
• Setting up real-time type checking in editors via the language server
• Migrating from mypy or Pyright to a faster type checker
• Configuring rule levels and suppression comments for type violations
• Working with advanced type system features like intersection types and redeclarations
• Needing fast incremental analysis in IDEs on large projects

Installation / Setup

Quick start without installation

uvx ty check

Add to your project (recommended)

uv add --dev ty
uv run ty check

To update:

uv lock --upgrade-package ty

Install globally with uv

uv tool install ty@latest
ty check

Standalone installer

macOS/Linux:

curl -LsSf https://astral.sh/ty/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/ty/install.ps1 | iex"

Other methods: pipx (pipx install ty), pip, mise, GitHub Releases, Docker, Bazel.

Core Concepts

Running the type checker

ty check              # Check all Python files in current directory
ty check example.py   # Check specific file
ty check --watch      # Watch mode with incremental rechecking

Configuration files

ty searches for pyproject.toml (reading [tool.ty]) or ty.toml in the current and parent directories. ty.toml takes precedence over pyproject.toml. User-level config: ~/.config/ty/ty.toml (macOS/Linux) or %APPDATA%\ty\ty.toml (Windows).

# pyproject.toml
[tool.ty.rules]
index-out-of-bounds = "ignore"

# ty.toml (equivalent, takes precedence if both exist)
[rules]
index-out-of-bounds = "ignore"

Rule levels

Each rule can be set to error (exit code 1), warn (warning only), or ignore (disabled). Configure via CLI flags (--error, --warn, --ignore) or in config files. Use all to set a default for all rules.

ty check --error all
ty check --ignore redundant-cast --warn unused-ignore-comment

Environment discovery

ty discovers installed packages from the active virtual environment (VIRTUAL_ENV), .venv in project root, or python3/python on PATH. Use --python to specify explicitly.

Python version targeting

By default, ty uses the lower bound of project.requires-python from pyproject.toml, then falls back to virtual environment metadata, then defaults to 3.14. Set explicitly with --python-version or environment.python-version.

Advanced Topics

Type System: Intersection types, redeclarations, gradual guarantee, fixpoint iteration → Type System

Configuration: Rules, overrides, environment settings, exclusions → Configuration

CLI Reference: Commands, options, exit codes, environment variables → CLI Reference

Editor Integration: VS Code, Neovim, Zed, PyCharm, Emacs, LSP features → Editor Integration

Suppression and FAQ: Suppression comments, typing questions, common issues → Suppression and FAQ