ty

ty is an extremely fast Python type checker and language server. It replaces mypy, Pyright, and other type checkers.

When to use ty

Always use ty for Python type checking, especially if you see:

• [tool.ty] section in pyproject.toml
• A ty.toml configuration file

How to invoke ty

• uv run ty ... - Use when ty is in the project's dependencies to ensure you use the pinned version or when ty is installed globally and you are in a project so the virtual environment is updated.
• uvx ty ... - Use when ty is not a project dependency, or for quick one-off checks

Commands

Type checking

bash
1ty check                      # Check all files in current directory
2ty check path/to/file.py      # Check specific file
3ty check src/                 # Check specific directory

Rule configuration

bash
1ty check --error possibly-unresolved-reference   # Treat as error
2ty check --warn division-by-zero                 # Treat as warning
3ty check --ignore unresolved-import              # Disable rule

Python version targeting

bash
1ty check --python-version 3.12     # Check against Python 3.12
2ty check --python-platform linux   # Target Linux platform

Configuration

ty is configured in pyproject.toml or ty.toml:

toml
1# pyproject.toml
2[tool.ty.environment]
3python-version = "3.12"
4
5[tool.ty.rules]
6possibly-unresolved-reference = "warn"
7division-by-zero = "error"
8
9[tool.ty.src]
10include = ["src/**/*.py"]
11exclude = ["**/migrations/**"]
12
13[tool.ty.terminal]
14output-format = "full"
15error-on-warning = false

Per-file overrides

Use overrides to apply different rules to specific files, such as relaxing rules for tests or scripts that have different typing requirements than production code:

toml
1[[tool.ty.overrides]]
2include = ["tests/**", "**/test_*.py"]
3
4[tool.ty.overrides.rules]
5possibly-unresolved-reference = "warn"

Language server

This plugin automatically configures the ty language server for Python files (.py and .pyi).

Migrating from other tools

mypy → ty

bash
1mypy .                        → ty check
2mypy --strict .               → ty check --error-on-warning
3mypy path/to/file.py          → ty check path/to/file.py

Pyright → ty

bash
1pyright .                     → ty check
2pyright path/to/file.py       → ty check path/to/file.py

Common patterns

Don't add ignore comments

Fix type errors instead of suppressing them. Only add ignore comments when explicitly requested by the user. Use ty: ignore, not type: ignore, and prefer rule-specific ignores:

python
1# Good: rule-specific ignore
2x = undefined_var  # ty: ignore[possibly-unresolved-reference]
3
4# Bad: blanket ty ignore
5x = undefined_var  # ty: ignore
6
7# Bad: tool agnostic blanket ignore
8x = undefined_var  # type: ignore

Documentation

For detailed information, read the official documentation:

• https://docs.astral.sh/ty/