laurigates/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

| Use this skill when... | Use basedpyright instead when... | Use mypy instead when... | |------------------------|----------------------------------|--------------------------| | Want fastest type checking (10-100x faster) | Need strictest defaults out of box | Need extensive plugin ecosystem | | Using Astral toolchain (uv, ruff) | Want Microsoft-backed alternative | Have legacy mypy configuration | | Need excellent diagnostics | Need Pylance compatibility | Require mypy-specific plugins | | Want incremental/watch mode | Team prefers Pyright conventions | Need Django/Pydantic mypy plugins | | Setting up new Python project | Already using basedpyright | Existing mypy expertise |

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

| Flag | Description | |------|-------------| | --python <VERSION> | Python environment/version to use | | --project <PATH> | Run within given project directory | | --config <PATH> | Path to ty.toml configuration file | | --verbose | Enable verbose output | | --hide-progress | Hide progress spinners/bars |

Rule Configuration

| Flag | Description | |------|-------------| | --error <RULE> | Treat rule as error severity | | --warn <RULE> | Treat rule as warning severity | | --ignore <RULE> | Ignore rule completely |

File Selection

| Flag | Description | |------|-------------| | --exclude <PATTERN> | Glob patterns for files to exclude | | --respect-ignore-files | Respect .gitignore (default) | | --no-respect-ignore-files | Ignore .gitignore files |

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

| Type Checker | Relative Speed | Notes | |--------------|----------------|-------| | ty | 1x (baseline) | Fastest, Rust-based | | Pyright | 10-60x slower | Good performance | | mypy | 10-100x slower | Slower but mature |

In editor (after file edit):

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

Feature Comparison

| Feature | ty | basedpyright | mypy | |---------|----|--------------| -----| | Speed | Fastest | Fast | Moderate | | LSP | Built-in | Built-in | dmypy | | Diagnostics | Excellent | Good | Basic | | Plugin system | Limited | Limited | Extensive | | Intersection types | First-class | Partial | Limited | | Ecosystem | Astral (uv, ruff) | Microsoft | Standalone |

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

| Context | Command | |---------|---------| | Quick check | ty check | | CI check | ty check --hide-progress | | Verbose debug | ty check --verbose | | Check module | ty check src/module/ | | Strict errors | ty check --error possibly-unbound | | Ignore rule | ty check --ignore unknown-type |

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/