Ty

ty: Python Type Checker & Language Server

ty (v0.0.34, May 2026) is Astral's Rust-based Python type checker and language server. Beta status: 0.0.x versioning, breaking changes between versions, and no stable API yet. Astral reports 10-100x faster checks than mypy and Pyright on large projects.

Formerly "Red-Knot", renamed May 2025, extracted from the ruff repo to astral-sh/ty.

When to Use ty

• [tool.ty] section in pyproject.toml or ty.toml exists
• Type checking Python code in any project
• Setting up an LSP for Python in your editor

When to wait: Projects heavily dependent on mypy plugins (Pydantic, Django, SQLAlchemy). ty has no plugin system and no plans to add one, first-class framework support is the stated approach instead.

How to Invoke

uvx ty check                  # One-off (latest)
uv run ty check               # Project dependency
ty check                      # Global install

CLI Commands

# Type checking
ty check                           # Check current directory
ty check path/to/file.py           # Specific file
ty check src/ tests/               # Multiple directories

# Rule severity
ty check --error unresolved-import
ty check --warn division-by-zero
ty check --ignore unresolved-attribute

# Python targeting
ty check --python-version 3.12
ty check --python-platform linux
ty check --python .venv/bin/python

# Output formats
ty check --output-format full      # Rich diagnostics (default)
ty check --output-format concise   # One line per error
ty check --output-format github    # GitHub Actions annotations
ty check --output-format gitlab    # GitLab Code Quality
ty check --output-format junit     # JUnit XML

# Watch mode
ty check --watch                   # Re-check on file changes
ty check -W                        # Short form

# Migration helper
ty check --add-ignore              # Auto-add ty: ignore comments for all errors

# Introspection
ty explain rule                    # List all rules
ty explain rule invalid-assignment # Explain specific rule

# Language server
ty server                          # Start LSP

Exit Codes

| Code | Meaning | | ---- | ------------------------------------------------------------ | | 0 | No errors (warnings don't count unless --error-on-warning) | | 1 | Type errors found | | 2 | CLI/configuration error |

Configuration

ty reads from ty.toml (takes precedence) or pyproject.toml under [tool.ty].

[tool.ty.environment]
python-version = "3.12"          # 3.7-3.15 allowed; unset falls back to 3.14
python-platform = "linux"        # win32|darwin|android|ios|linux|all
python = ".venv"                 # Path to environment/interpreter
root = ["src"]                   # First-party module discovery
extra-paths = []                 # Additional resolution paths

[tool.ty.rules]
unresolved-import = "error"
division-by-zero = "ignore"
possibly-unresolved-reference = "warn"

[tool.ty.analysis]
allowed-unresolved-imports = ["mypackage._internal.*"]
replace-imports-with-any = ["legacy_lib.*"]
respect-type-ignore-comments = true

[tool.ty.src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**"]
respect-ignore-files = true

[tool.ty.terminal]
output-format = "full"
error-on-warning = false

Per-File Overrides

[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]

[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"
unresolved-attribute = "ignore"

Suppression Comments

# Preferred: rule-specific
x = foo  # ty: ignore[possibly-unresolved-reference]

# Broad (discouraged)
x = foo  # ty: ignore

# Legacy (honored by default, configurable)
x = foo  # type: ignore

Rule: Fix type errors instead of suppressing. Only add ignore comments when explicitly requested. Always prefer rule-specific ignores.

What Makes ty Unique

Unknown vs Any

ty distinguishes between Any (deliberate opt-out) and Unknown (inferred gap). This is the "gradual guarantee", all code is checked, but unknowns are treated permissively rather than skipped entirely (mypy skips unannotated functions by default).

Intersection Types

ty supports A & B intersection types natively, not available in mypy or pyright.

Fine-Grained Incrementality

Built on Salsa (same framework as rust-analyzer). Changing one function re-parses only that function and its dependents, not the entire file. This powers sub-millisecond editor responses.

Performance

| Project | ty | pyright | mypy | | --------------------- | --------- | ------- | ------ | | home-assistant (cold) | 2.19s | 19.62s | 45.66s | | PyTorch (cold) | 4.04s | 262.74s | — | | PyTorch (incremental) | 4.7ms | 386ms | — |

Editor/LSP Setup

ty ships a full LSP with go-to-definition, find references, auto-complete with auto-import, rename, inlay hints, and hover.

VS Code: Install astral-sh.ty extension.

Neovim (>=0.11):

vim.lsp.config('ty', { settings = { ty = {} } })
vim.lsp.enable('ty')

**Neovim ( ty check mypy --strict . -> ty check --error-on-warning # (partial) mypy -p mypackage -> ty check src/mypackage/ # paths, not modules mypy --python-version 3.11 -> ty check --python-version 3.11

### From pyright

```bash
pyright .                     ->  ty check
pyright path/to/file.py       ->  ty check path/to/file.py

Anti-Patterns

| Anti-Pattern | Fix | | --------------------------------------------------- | ------------------------------------------------------------ | | Blanket # ty: ignore everywhere | Fix errors or use rule-specific ignores | | Using # type: ignore in new code | Use # ty: ignore[rule-name] | | Expecting mypy plugin behavior | Check limitation table; wait for framework support if needed | | Running ty on unannotated code expecting strictness | Add ruff ANN rules for annotation enforcement | | Pinning to latest without testing | Pin version in CI, test upgrades deliberately |

What This Skill is NOT

• Not a replacement for ty explain rule for rule details
• Not for linting or formatting (use ruff)
• Not for package management (use uv)
• Not a mypy drop-in replacement yet (plugin gap, beta stability)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hyperb1iss
• Source: hyperb1iss/hyperskills
• License: MIT
• Homepage: https://hyperbliss.tech

Install and usage instructions live in the source repository linked above.