ty Type Checking

@laurigates/ty Type Checking

3 forks

Updated 4/6/2026

ty-type-checking: Python type checking with ty, Astral's extremely fast type checker (10-100x faster than mypy/Pyright). Use when checking Python types, configuring type checking rules, or setting up type checking in projects. Triggered by: ty, type checking, type errors, static analysis, mypy alternative, pyright alternative.

Installation

$npx agent-skills-cli install @laurigates/ty Type Checking

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorylaurigates/claude-plugins

Pathpython-plugin/skills/ty-type-checking/SKILL.md

Branchmain

Scoped Name@laurigates/ty Type Checking

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions

model: haiku created: 2026-01-29 modified: 2026-01-29 reviewed: 2026-01-29 name: ty-type-checking description: | Python type checking with ty, Astral's extremely fast type checker (10-100x faster than mypy/Pyright). Use when checking Python types, configuring type checking rules, or setting up type checking in projects. Triggered by: ty, type checking, type errors, static analysis, mypy alternative, pyright alternative. user-invocable: false allowed-tools: Bash(ty ), Bash(python ), Bash(uv *), Read, Edit, Write, Grep, Glob, TodoWrite

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

Command-line arguments (highest priority)
ty.toml in current directory
pyproject.toml [tool.ty] section
User config: ~/.config/ty/ty.toml (Linux) or %APPDATA%\ty\ty.toml (Windows)
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

Install extension: astral-sh.ty
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"]

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/

More by laurigates

View all

document-linking

Unified ID system for PRDs, ADRs, PRPs, and GitHub issues. Auto-generates IDs on document access, maintains bidirectional links, and provides traceability across all artifacts.

github-issue-writing

Create well-structured GitHub issues with clear titles, descriptions, and acceptance criteria. Use when filing bugs, requesting features, or structuring issue content.

delegation-first

Default behavior pattern that automatically delegates implementation tasks to specialized sub-agents while keeping the main conversation focused on architecture, design, and strategy. Use when receiving ANY implementation request - the main Claude acts as architect/coordinator while sub-agents handle code, tests, debugging, and documentation.

release-please-standards

Release-please standards and configuration. Use when configuring release-please workflows, checking release automation compliance, or when the user mentions release-please, automated releases, or version management.

ty Type Checking

Installation

Details

Usage

Skill Instructions

ty Type Checking

When to Use This Skill

Core Expertise

Installation

Via uv (Recommended)

Via pip

VS Code Extension

Basic Usage

Type Checking

Output Control

Configuration

pyproject.toml

ty.toml (standalone)

Configuration Hierarchy

CLI Options

Core Options

Rule Configuration

File Selection

Editor Integration

VS Code

Neovim

PyCharm

CI Integration

GitHub Actions

Pre-commit Hook

GitLab CI

Common Patterns

Quick Type Check

Configuring Rule Severity

Excluding Files

Comparison with Other Type Checkers

Performance

Feature Comparison

Migration

From mypy

From Pyright/basedpyright

Best Practices

1. Use with Astral Toolchain

2. Configure Project-Level Settings

3. CI with Hide Progress

4. Incremental Adoption

Agentic Optimizations

Quick Reference

Essential Commands

Minimal Configuration

See Also

References

More by laurigates