Ty Type Checking

ty Type Checking

Expert knowledge for using ty as an extremely fast Python type checker from Astral (creators of uv and ruff).

When to Use This Skill

Core Expertise

ty Advantages

• Extremely fast (10-100x faster than mypy and Pyright)
• Written in Rust for performance
• Best-in-class diagnostic messages inspired by Rust compiler
• Incremental analysis optimized for IDE workflows
• Built-in LSP for editor integration
• First-class intersection types
• Advanced type narrowing and reachability analysis
• Part of Astral ecosystem (uv, ruff)

Installation

Via uv (Recommended)

# Install globally as tool
uv tool install ty@latest

# Run without installing
uvx ty check

# Install as dev dependency
uv add --dev ty

Via pip

pip install ty

VS Code Extension

Install the astral-sh.ty extension from the VS Code marketplace.

Basic Usage

Type Checking

# Check current directory
ty check

# Check specific files or directories
ty check src/
ty check src/ tests/
ty check path/to/file.py

# Verbose output
ty check --verbose

# Hide progress indicators
ty check --hide-progress

Output Control

# Default output with diagnostics
ty check

# Hide progress spinners (useful for CI)
ty check --hide-progress

# Verbose mode for debugging
ty check --verbose

Configuration

pyproject.toml

[tool.ty]
# Python version targeting
python-version = "3.12"

# Files to exclude
exclude = [
    "**/__pycache__",
    "**/.venv",
    "**/node_modules",
    "tests/fixtures/**",
]

[tool.ty.rules]
# Configure rule severity: "error", "warn", or "ignore"
index-out-of-bounds = "error"
possibly-unbound = "warn"
unknown-type = "ignore"

ty.toml (standalone)

# ty.toml takes precedence over pyproject.toml
python-version = "3.12"

exclude = [
    "**/__pycache__",
    "**/.venv",
]

[rules]
index-out-of-bounds = "error"
possibly-unbound = "warn"

Configuration Hierarchy

1. Command-line arguments (highest priority)
2. ty.toml in current directory
3. pyproject.toml [tool.ty] section
4. User config: ~/.config/ty/ty.toml (Linux) or %APPDATA%\ty\ty.toml (Windows)
5. ty defaults (lowest priority)

CLI Options

Core Options

Rule Configuration

File Selection

Editor Integration

VS Code

1. Install extension: astral-sh.ty
2. ty provides LSP with:
   • Real-time type checking
   • Go to Definition
   • Auto-complete with type hints
   • Auto-import suggestions
   • Rename symbol
   • Inlay hints
   • Semantic highlighting

Neovim

-- Using nvim-lspconfig
require("lspconfig").ty.setup({
  settings = {
    ty = {
      -- Configuration options
    }
  }
})

PyCharm

ty provides a PyCharm plugin for IDE integration.

CI Integration

GitHub Actions

name: Type Check

on: [push, pull_request]

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v2
        with:
          enable-cache: true

      - name: Run ty
        run: uvx ty check --hide-progress

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ty
    rev: v0.0.10
    hooks:
      - id: ty

GitLab CI

ty-check:
  stage: test
  image: python:3.12
  before_script:
    - pip install ty
  script:
    - ty check --hide-progress

Common Patterns

Quick Type Check

# Fast check of current project
ty check

# Check specific module
ty check src/api/

# Check with custom Python version
ty check --python 3.11

Configuring Rule Severity

# Make specific rules errors
ty check --error index-out-of-bounds --error possibly-unbound

# Ignore noisy rules
ty check --ignore unknown-type

# Mix severities
ty check --error division-by-zero --warn possibly-unbound --ignore unknown-type

Excluding Files

# Exclude test fixtures
ty check --exclude "tests/fixtures/**"

# Exclude multiple patterns
ty check --exclude "**/*_test.py" --exclude "**/conftest.py"

# Don't respect .gitignore
ty check --no-respect-ignore-files

Comparison with Other Type Checkers

Performance

In editor (after file edit):

• ty: ~5ms to recompute diagnostics
• Pyright: ~400ms
• mypy: Several seconds

Feature Comparison

Migration

From mypy

# mypy.ini / [tool.mypy]
[mypy]
python_version = 3.12
strict = true
warn_unused_ignores = true

# Equivalent ty configuration
[tool.ty]
python-version = "3.12"

[tool.ty.rules]
# Configure equivalent strictness via rules

From Pyright/basedpyright

# [tool.pyright] or [tool.basedpyright]
[tool.basedpyright]
pythonVersion = "3.12"
typeCheckingMode = "strict"

# Equivalent ty configuration
[tool.ty]
python-version = "3.12"

[tool.ty.rules]
# Configure strictness via rules

Best Practices

1. Use with Astral Toolchain

# Combine with uv and ruff for complete workflow
uv init my-project && cd my-project
uv add --dev ty ruff
uv run ty check
uv run ruff check --fix

2. Configure Project-Level Settings

# pyproject.toml - recommended setup
[tool.ty]
python-version = "3.12"
exclude = [
    "**/__pycache__",
    "**/.venv",
    "**/build",
    "**/dist",
]

[tool.ty.rules]
# Start with defaults, adjust as needed

3. CI with Hide Progress

# Always use --hide-progress in CI for cleaner logs
ty check --hide-progress

4. Incremental Adoption

# Start by checking new code only
ty check src/new_module/

# Gradually expand coverage
ty check src/

Agentic Optimizations

Quick Reference

Essential Commands

# Basic type checking
ty check                          # Check current directory
ty check src/                     # Check specific directory
ty check file.py                  # Check specific file

# Configuration
ty check --config ty.toml         # Use custom config
ty check --python 3.12            # Specify Python version

# Output control
ty check --verbose                # Verbose output
ty check --hide-progress          # No progress indicators

# Rule control
ty check --error RULE             # Treat as error
ty check --warn RULE              # Treat as warning
ty check --ignore RULE            # Ignore rule

# File selection
ty check --exclude "pattern"      # Exclude files

Minimal Configuration

# pyproject.toml
[tool.ty]
python-version = "3.12"
exclude = ["**/__pycache__", "**/.venv"]

See Also

• basedpyright-type-checking - Alternative type checker with stricter defaults
• ruff-linting - Fast linting from same ecosystem
• ruff-formatting - Fast formatting from same ecosystem
• python-development - General Python development patterns

References

• Official docs: https://docs.astral.sh/ty/
• GitHub: https://github.com/astral-sh/ty
• Blog announcement: https://astral.sh/blog/ty
• Playground: https://play.ty.dev/