ty - Fast Python Type Checker Cheatsheet
ty is an extremely fast Python type checker and language server, written in Rust by Astral (the team behind Ruff and uv). It applies the same performance philosophy to type checking: where mypy can take minutes on a large codebase, ty targets near-instant feedback, making type checking practical to run on every save rather than only in CI. It completes the modern Astral Python toolchain — uv for packaging, Ruff for lint/format, ty for types.
ty is newer than mypy and still maturing. Validate it against your codebase before making it a hard CI gate.
Installation
| Method | Command |
|---|
| uv (recommended) | uv tool install ty |
| uvx (no install) | uvx ty check |
| pip | pip install ty |
| Verify | ty --version |
Checking Code
| Command | Description |
|---|
ty check | Check the current project |
ty check src/ | Check a specific path |
ty check --watch | Re-check on file changes |
ty check --output-format concise | Compact output |
ty check --error-on-warning | Treat warnings as errors |
ty --help | Full option list |
Configuration
ty reads pyproject.toml:
[tool.ty]
# Paths to check
src = ["src", "tests"]
[tool.ty.environment]
python-version = "3.12"
# Where to find dependencies
python = ".venv"
[tool.ty.rules]
# Tune individual diagnostics
possibly-unbound-attribute = "warn"
unused-ignore-comment = "ignore"
| Section | Purpose |
|---|
[tool.ty] | Project layout / included paths |
[tool.ty.environment] | Python version, venv, search paths |
[tool.ty.rules] | Set each rule to error, warn, or ignore |
Suppressing Diagnostics
| Form | Effect |
|---|
# ty: ignore | Suppress all diagnostics on the line |
# ty: ignore[rule-name] | Suppress a specific rule |
# type: ignore | Also respected (mypy-compatible) |
Language Server (Editor Integration)
| Editor | How |
|---|
| VS Code | Install the Astral ty extension |
| Neovim | Configure ty server as an LSP |
| Any LSP client | Run ty server |
The language server gives inline type errors, hover types, and go-to-definition with the same speed as the CLI.
Typical Diagnostics
| Diagnostic | Means |
|---|
invalid-argument-type | Argument doesn’t match the parameter type |
unresolved-attribute | Attribute doesn’t exist on the type |
possibly-unbound-variable | Variable may be used before assignment |
invalid-return-type | Return doesn’t match the annotation |
unresolved-import | Import cannot be resolved |
# A complete modern Python quality gate
uv sync # deps, locked and fast
uv run ruff format . # format
uv run ruff check . # lint
uv run ty check # types
uv run pytest # tests
| Tool | Replaces |
|---|
| uv | pip, pip-tools, virtualenv, pyenv, poetry |
| Ruff | black, flake8, isort, pyupgrade, + more |
| ty | mypy (type checking) |
CI Integration
# Fail the build on type errors
uvx ty check --error-on-warning
# Only check changed files (with git)
git diff --name-only origin/main -- '*.py' | xargs uvx ty check
ty vs Other Type Checkers
| Aspect | ty | mypy | Pyright |
|---|
| Language | Rust | Python | TypeScript/Node |
| Speed | Very fast | Slower | Fast |
| Maturity | Newer | Most mature | Mature |
| Editor LSP | Built-in | Via plugins | Built-in (Pylance) |
| Best for | Speed + Astral stack | Ecosystem compatibility | VS Code users |
Resources
