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/