ty

ty is an extremely fast Python type checker written in Rust by Astral, delivering 10-100x performance improvements over mypy and Pyright while offering advanced typing features and comprehensive diagnostics.

Performance

ty’s speed is its defining characteristic:

• Home Assistant project: 2.19 seconds (vs mypy’s 45.66 seconds) = 20x faster
• Diagnostic recomputation: 4.7ms after file edits (vs Pyright’s 386ms) = 80x faster
• Thousands of files: Scans 2,871 Python files in seconds
• Incremental architecture: Live updates in IDEs provide near-instant feedback

Core Command

ty check                    # Type-check current directory  
ty check path/to/code/      # Type-check specific path  
uvx ty check               # Run via uv  

Advanced Type System Features

• First-class intersection types (A & B) for precise type narrowing
• Sophisticated reachability analysis detects unreachable code branches (useful for version-specific paths)
• Advanced type narrowing refines types through code flow analysis
• Designed for gradual typing: Supports partial annotations and redeclarations without false positives

Comprehensive Diagnostics

• Color-coded output with severity levels (error, warning, info)
• Multi-file context showing why something is wrong and often how to fix it
• Structured format for CI/CD pipelines via --output-format flag
• Best-in-class error messages inspired by Rust compiler

Configuration and Flexibility

Python Version Support

ty check --python-version 3.11          # Specify Python version  

Cross-Platform Type Checking

ty check --platform linux               # Check platform-specific code  
ty check --platform all                 # Check all platforms  

Module Discovery

• Automatically discovers first-party and third-party modules
• Analyzes pyproject.toml and project structure
• Supports src layout, flat layout, and other patterns
• Respects .gitignore and .ignore files

Supported File Types

• Python files (.py)
• Stub files (.pyi)
• Jupyter Notebooks (.ipynb)

Language Server Protocol (LSP)

ty ships with full LSP implementation enabling IDE integration:

• Code navigation: Go to definition, find references
• Completions: Auto-import, symbol completion
• Diagnostics: Live type checking as you edit
• Refactoring: Rename symbols, code actions
• Hints: Inlay hints, hover information
• Incremental updates: Fast live feedback in large codebases

Inline Suppression

# type: ignore              # Disable all rules  
# ty: ignore[E001]          # Disable specific rules  

Current Status and Roadmap

• Status: Beta (as of January 2026)
• Maturity: Not production-ready but excellent for development and experimentation
• Stable release: Planned for 2026
• Design: Supports real-world codebases with partial annotations

Future Integration

Astral plans to combine ty with ruff for additional capabilities:

• Dead code elimination
• Type-aware linting
• Unified ecosystem with uv and ruff

Key Advantages

• Exceptional speed makes on-save checking practical
• Advanced typing features beyond mypy/Pyright
• Gradual typing support reduces friction in existing codebases
• IDE-first design with incremental analysis
• Rich diagnostics explain problems clearly

When to Use

ty is ideal for:

• Development and experimentation (not yet production)
• Teams wanting fast feedback loops
• Projects adopting the full Astral stack (uv + ruff + ty)
• Codebases transitioning to type checking
• IDE workflows benefiting from live type checking

Limitations

• Beta status means some features may be missing
• Not a drop-in replacement for mypy/Pyright yet
• Some edge cases may behave differently
• Still receiving bug fixes and feature expansion

See Also

• astral
• ruff
• uv