Ty

ty

ty is an extremely fast Python type checker and language server written in Rust. It's backed by Astral, the creators of uv and Ruff. ty is currently in beta with 0.0.x versioning — breaking changes may occur between versions.

Key highlights:

• 10x–100x faster than mypy and Pyright
• Comprehensive diagnostics with rich contextual information
• Language server (LSP) with code navigation, completions, auto-import, inlay hints
• Fine-grained incremental analysis for fast IDE updates
• Designed for adoption: supports redeclarations, partially typed code, and gradual typing
• Editor integrations: VS Code, PyCharm, Neovim, and more

Docs: https://docs.astral.sh/ty/

Quick Start

Run type checking without installation:

uvx ty check                 # Check all Python files in current directory
uvx ty check path/to/file.py # Check a specific file
uvx ty check --watch .       # Watch mode — re-runs on file changes

Or start a language server for editor integration:

uvx ty server                # Start LSP server on stdin/stdout

Online playground: Try ty in your browser at https://play.ty.dev

Installation

Add to project (recommended)

# Using uv (recommended)
uv add --dev ty

# Then use it
uv run ty check

# Or upgrade
uv lock --upgrade-package ty

Global installation

# Install globally with uv
uv tool install ty@latest

# Or with pip / pipx
pip install ty
pipx install ty

# Or via mise
mise install ty

Standalone installer

Use the official Astral installation docs for platform-specific installer instructions:

• https://docs.astral.sh/ty/getting-started/installation/

Docker

COPY --from=ghcr.io/astral-sh/ty:latest /ty /bin/

Available tags: ghcr.io/astral-sh/ty:latest, ghcr.io/astral-sh/ty:0.0.26, ghcr.io/astral-sh/ty:0.0

Core Commands

ty check [FILES/DIRS]         # Type-check Python files (default: all in cwd)
ty check --watch .            # Watch mode — re-runs on file changes
ty check --python /path/to/python  # Specify Python interpreter
ty check --python-version 3.12 # Target specific Python version
ty check --config-file ty.toml # Use specific config file
ty check --output-format json  # Machine-readable JSON output
ty check --output-format text  # Human-readable output (default)
ty check --exclude '*.pyi' .   # Exclude files by pattern
ty check --select rule1,rule2 . # Only check specific rules
ty check --ignore rule1,rule2 . # Ignore specific rules
ty server                      # Start LSP server for editor integration
ty generate-shell-completion bash # Generate shell completions

Configuration

ty reads from pyproject.toml (under [tool.ty]) or ty.toml. Configuration is optional — ty works out-of-the-box on most projects.

Minimal config (pyproject.toml)

[tool.ty]
# Configuration goes here

Or create a dedicated ty.toml:

# Root directories for first-party module resolution
[environment]
root = ["./src", "."]

# Python version and environment
[environment]
python-version = "3.12"
python = ".venv/bin/python3"  # Path to interpreter or venv

# Rule severity configuration
[rules]
possibly-unbound = "warn"       # Warn on possibly-unbound variables
division-by-zero = "error"      # Error on division by zero
invalid-argument-type = "warn"  # Warn on type mismatches
unresolved-import = "error"     # Error on missing imports

Comprehensive config example

# Environment configuration
[environment]
# Root directories for resolving first-party imports (priority order)
root = ["./src", "./lib", "."]

# Python interpreter or venv path
python = ".venv"

# Target Python version (affects standard library stubs and syntax features)
python-version = "3.12"

# Target platform (win32, darwin, linux, ios, android, all)
python-platform = "darwin"

# Extra module search paths (like mypy's MYPYPATH)
extra-paths = ["./vendor"]

# Path to typeshed for standard library types
typeshed = "/path/to/typeshed"

# Module import handling
[analysis]
# Suppress unresolved-import errors for modules matching these patterns
allowed-unresolved-imports = ["pandas.**", "numpy.**", "!pandas.core"]

# Replace module types with Any (even if found)
replace-imports-with-any = ["sklearn.**"]

# Support type: ignore comments (default: true)
respect-type-ignore-comments = true

# Rule severity (values: ignore, warn, error)
[rules]
all = "warn"                           # Default: all rules as warnings
possibly-unbound = "error"             # Override: specific rules as errors
invalid-argument-type = "warn"
unresolved-import = "error"
division-by-zero = "ignore"

# Per-file rule overrides
[rules.overrides]
"tests/**/*.py" = { all = "warn" }
"*_test.py" = { invalid-argument-type = "ignore" }

Rule Categories (Common Types)

Use the rules documentation for the complete list and details on each rule.

Suppressing Errors

Inline suppression

# Suppress on a single line
x = bad_function()  # ty: ignore[invalid-argument-type]

# Suppress multiple rules
y = other()  # ty: ignore[unresolved-import, possibly-unbound]

# Suppress all rules on line (avoid overusing)
z = something()  # ty: ignore

type: ignore support

By default, ty respects type: ignore comments (compatible with mypy/Pyright):

x = bad_call()  # type: ignore

Disable this in config if you prefer only ty: ignore:

[analysis]
respect-type-ignore-comments = false

Module-level suppression

At the top of a file:

# ty: ignore-errors

This suppresses all errors in the file.

Watch Mode & Development

Incremental type checking with watch mode

ty uses fine-grained incrementality — it only re-analyzes affected files when you edit:

ty check --watch .

This is excellent for IDE integration. The language server (ty server) uses the same incremental engine.

Editor Integration

VS Code

Install the official extension: Astral ty (astral-sh.astral-python-types)

The extension automatically runs the ty language server and provides:

• Real-time diagnostics
• Code navigation (Go to Definition)
• Completions and auto-imports
• Hover information
• Inlay hints

PyCharm

1. Go to Settings → Languages & Frameworks → Python → Type Checker
2. Select "ty" from the dropdown
3. Configure the path to the ty binary

Neovim

Use a plugin like nvim-lspconfig to connect to the ty language server:

local lspconfig = require('lspconfig')
lspconfig.ty.setup {}  -- Requires LSP binary

Or use cmp-ty for completion support.

Other editors

ty provides an LSP server. Configure your editor to run:

ty server

And point to the language server capabilities. See the editor integration docs.

Integration with uv

ty integrates seamlessly with uv, Astral's fast Python package manager:

# Install ty in your project
uv add --dev ty

# Type-check using the project environment
uv run ty check

# Type-check in watch mode
uv run ty check --watch .

# Start the language server
uv run ty server

When run via uv run, ty automatically uses the project's virtual environment for resolving dependencies.

Language Server Protocol (LSP)

The ty server command starts an LSP server for editor integration. It provides:

• Real-time diagnostics — errors/warnings as you type
• Code navigation — Go to Definition, Find References
• Completions — Context-aware suggestions with auto-import
• Hover information — Type signatures and documentation
• Inlay hints — Type annotations inline
• Code actions — Quick fixes and refactoring suggestions
• Auto-import — Automatically add imports for undefined names
• Fine-grained incrementality — Fast updates after edits

Example editor configuration (for generic LSP setup):

ty server  # Runs on stdin/stdout

Type Checking in CI/CD

GitHub Actions

name: Type Check
on: [push, pull_request]
jobs:
  ty:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-astral@v0
        with:
          tool: ty
      - run: ty check --output-format github

Or with uv:

      - uses: astral-sh/setup-astral@v0
      - run: uv run ty check --output-format github

JSON output for CI pipelines

ty check --output-format json > results.json

This produces machine-readable diagnostics that CI systems can parse.

Configuration File Formats

pyproject.toml style

[tool.ty]
# ... configuration

ty.toml style (standalone)

[environment]
python-version = "3.12"

[rules]
all = "warn"

Both are equivalent — use whichever your project prefers. The ty.toml is loaded if present, otherwise ty looks for [tool.ty] in pyproject.toml.

Comparison with mypy and Pyright

Migration notes:

• type: ignore comments work the same way (or disable them in config)
• Error codes are different (ty uses its own system, not mypy's)
• Configuration is simpler than mypy's config file
• Gradual typing and partially-typed code are first-class features

Common Workflows

Check all Python files

ty check

ty walks the project and checks all .py files.

Check specific file or directory

ty check src/mymodule.py
ty check tests/

Fix issues (limited support in beta)

Some rules support auto-fixes; check the documentation for which ones. Use --no-fix to preview changes without applying:

# Note: auto-fix support is still developing in ty beta
# For now, rely on manual fixes or other tools

Exclude files or directories

# Command line
ty check --exclude '*.pyi' --exclude 'build/*' .

# Or in config
# (ty.toml or pyproject.toml)
[tool.ty]
# Configure exclusions (see docs for exact syntax)

Run with specific Python version

ty check --python-version 3.10 .

JSON output for parsing

ty check --output-format json

Limitations in Beta

• 0.0.x versioning — Breaking changes may occur between versions
• Fewer rules than mypy/Pyright — ty covers ~70% of common cases; if you need every edge case, consider hybrid approaches
• Limited auto-fix support — Most fixes require manual changes; ty is primarily a checker, not a formatter
• Type system features — Advanced generics, TypeVar constraints, and protocol edge cases may not be fully supported yet
• Third-party stubs — py.typed packages are supported, but some legacy packages may need allowed-unresolved-imports workarounds

See the type system support tracking issue for detailed feature status.

Best Practices for Adoption

1. Start with the defaults — ty's default rules are well-balanced. No need to configure much upfront.

2. Use in watch mode during development — Combine ty check --watch with your editor for real-time feedback:

   ty check --watch .
   

3. Gradual adoption — You can suppress errors selectively and fix them incrementally:

   result = untyped_function()  # ty: ignore[invalid-argument-type]
   

4. Allow unresolved imports temporarily — When migrating, temporarily suppress errors for untyped dependencies:

   [analysis]
   allowed-unresolved-imports = ["django.**", "requests.**"]
   

5. Combine with uv — Use uv add --dev ty and uv run ty check to keep ty in sync with your project environment.

6. Integrate into CI — Add ty check --output-format github to your CI pipeline so issues are surfaced on PRs.

7. Don't aim for 100% coverage immediately — ty is designed for adoption. Start with core files, then expand. Use rule severity to prioritize errors as warn before promoting to error.

8. Pin the version — Since ty is in beta with 0.0.x versioning, pin it in your project:

   uv add --dev ty==0.0.26  # or latest
   

9. Use the language server — Combine ty check in CI with ty server for IDE integration. The server's fine-grained incrementality makes development fast.

10. Reference the rules — Use https://docs.astral.sh/ty/rules/ to understand each error. ty's error messages are detailed and actionable.

Troubleshooting

"Unresolved import" errors for installed packages

Cause: ty can't find your Python environment.

Solution:

# Explicitly point to your interpreter
ty check --python /path/to/python .

# Or use uv run to set the environment
uv run ty check .

# Or set VIRTUAL_ENV
export VIRTUAL_ENV=/path/to/venv
ty check

Type checking is slow

Cause: Likely the first run before caching, or incremental analysis hasn't kicked in.

Solution:

• Use watch mode for development (enables incremental analysis):

  ty check --watch .
  

• Subsequent runs are much faster due to ty's fine-grained incrementality

False positives or odd errors

Cause: ty is in beta; some edge cases may not be fully supported.

Solution:

• Suppress with # ty: ignore temporarily
• Check the tracking issue for known limitations
• Report bugs on GitHub

Can't find ty command

Cause: Not installed or not in PATH.

Solution:

# Try uvx
uvx ty check .

# Or install globally
uv tool install ty
ty check .

# Or add to project
uv add --dev ty
uv run ty check .

Resources

• Official Docs: https://docs.astral.sh/ty/
• GitHub Repository: https://github.com/astral-sh/ty
• Online Playground: https://play.ty.dev
• Rules Documentation: https://docs.astral.sh/ty/rules/
• Type System Features: https://docs.astral.sh/ty/features/type-system/
• Language Server Info: https://docs.astral.sh/ty/features/language-server/
• Issue Tracker: https://github.com/astral-sh/ty/issues
• Discord Community: https://discord.com/invite/astral-sh