Ty

ty — Python Type Checker

Overview

ty is Astral's type checker and language server for Python, written in Rust — 10–100x faster than mypy and pyright. One binary does two jobs: ty check (CLI) and ty server (LSP).

⚠️ Read this first: ty is beta

This skill is documented against ty 0.0.72 (2026-08-14). ty is 0.0.x: CLI flags, rule names, and config keys change between patch releases. Always confirm the running build:

ty --version                     # ty 0.0.72 (62ebbecc7 2026-08-14)
ty version --output-format json  # machine-readable

Because everything here is that new, this skill does not tag individual features with version numbers — instead see Recently changed for the handful of things where you may hold stale knowledge, and verify anything surprising against ty check --help and ty explain rule <name> on your build.

Mental model (read this before configuring anything)

ty is inference-first and adoption-oriented, not annotation-gated. Four consequences that surprise people arriving from mypy or pyright:

Unknown is the type you will see most while adopting: it means "ty could not infer this", behaves like Any, and is what keeps untyped code from erroring. (@Todo is different — it signals a gap in ty itself, not in your code.)

Disambiguation — what this skill is NOT:

• Not ruff — Ruff is Astral's linter/formatter. ty does no linting or formatting; where a check has no ty rule (e.g. "require annotations"), the answer is usually a Ruff rule.
• Not uv — uv is Astral's packaging/project manager. It only appears here as the delivery mechanism (uvx ty, uv add --dev ty).
• Not mypy or pyright — ty is an alternative to them, with its own rule names, config keys, and suppression syntax. See Coming from mypy or pyright.
• No plugin system — ty has none and plans none (so no mypy-plugin equivalent for pydantic/django/SQLAlchemy; ty is adding such library support natively instead).

When to Use This Skill

Install & run

uvx ty@latest check           # zero-install, pinned to a known version (recommended for one-offs)
uv add --dev ty && uv run ty check   # pin per-project so the whole team matches
uv tool install ty@latest     # global; `uv tool upgrade ty` to update
pipx install ty               # or: pip install ty
curl -LsSf https://astral.sh/ty/install.sh | sh   # standalone installer

In a project, run ty inside the environment (uv run ty check, or with .venv activated) so it can see your dependencies. Docker: COPY --from=ghcr.io/astral-sh/ty:latest /ty /bin/. Pre-commit hook: astral-sh/ty-pre-commit.

Commands

Full flag reference: references/cli-reference.md.

Configuration

ty reads [tool.ty] from pyproject.toml, or a ty.toml with the same shape minus the tool.ty. prefix. ty.toml wins if both exist in a directory. There is also user-level config at ~/.config/ty/ty.toml; project config overrides it, and CLI flags override everything.

Six tables — environment, src, rules, overrides, terminal, analysis:

# pyproject.toml
[tool.ty.environment]
python = ".venv"                 # interpreter, venv dir, or sys.prefix dir
python-version = "3.12"          # else: requires-python lower bound → venv → latest supported
python-platform = "linux"        # or "all" to make no sys.platform assumption
root = ["./src"]                 # first-party search roots (NOT src.root — see below)
extra-paths = ["./stubs"]        # highest-priority module resolution (~ MYPYPATH / stubPath)

[tool.ty.src]
include = ["src", "tests"]
exclude = ["src/generated", "!**/build/"]   # leading `!` re-includes a default exclusion
respect-ignore-files = true      # honor .gitignore/.ignore

[tool.ty.rules]
possibly-unresolved-reference = "warn"
redundant-cast = "ignore"

[[tool.ty.overrides]]            # per-file-pattern rule levels
include = ["tests/**"]
rules = { possibly-missing-attribute = "ignore" }

[tool.ty.terminal]
output-format = "concise"        # full | concise | gitlab | github | junit

include/exclude use anchored gitignore-style globs: src means <root>/src only — use **/src to match at any depth. Paths passed explicitly on the command line bypass exclude (unless --force-exclude).

Environment discovery is where type checkers actually fail. ty finds third-party packages via VIRTUAL_ENV → an activated Conda env → a .venv in the project root → python3/python on PATH. If imports don't resolve, that chain is almost always the cause — see Troubleshooting.

Every key, its default, and all environment variables: references/configuration.md.

Rule levels & suppression

Three levels, not on/off: error (exit 1), warn (still exit 1 by default — see exit codes), ignore (off). Of ty's 126 rules, 93 are error, 23 are warn, and 10 are ignore (opt-in) by default.

Set them on the CLI (repeatable; later wins; all targets every rule):

ty check --warn unused-ignore-comment --ignore redundant-cast --error possibly-missing-import
ty check --error all          # everything at error — allowed, but not recommended

Don't memorize the rule catalog — look rules up. ty explain rule <name> prints the "what it does / why it's bad / example" doc for the rule in the diagnostic you're staring at, and misspelled names get a "did you mean" suggestion. ty explain rule --output-format json dumps every rule with its default_level — that's the machine-readable catalog. Online: docs/reference/rules.md.

Suppression — ty's own syntax carries the rule code in brackets:

a = 10 + "test"           # ty: ignore[unsupported-operator]
f(1, 2)                   # ty: ignore[missing-argument, invalid-argument-type]
x = g()                   # type: ignore[arg-type, ty:invalid-argument-type]  # shared with mypy

ty also honors bare PEP 484 # type: ignore (suppresses everything on the line), and # type: ignore[ty:<rule>] behaves exactly like # ty: ignore[<rule>] — non-ty:-prefixed codes are skipped, so one comment can serve two checkers. A # ty: ignore[...] on its own line before any Python code applies file-wide. @no_type_check silences a whole function (not a class).

The unused-ignore-comment rule (warn by default) catches suppressions you no longer need — and it can only be suppressed by # ty: ignore[unused-ignore-comment], never by a bare # ty: ignore or # type: ignore.

Adopting ty on an existing codebase: ty check --add-ignore writes # ty: ignore[rule] comments for every current diagnostic, giving you a green baseline to burn down. It rewrites your source files in place and exits 0 — run it on a clean working tree and read the diff, because it will just as happily suppress a real bug. It is not a fixer: --fix is the flag that applies actual code fixes, and most type errors have none.

More: references/rules-and-suppression.md.

Diagnostics & exit codes

Default full output shows the offending span plus contextual annotations (e.g. where the parameter was declared); --output-format concise gives one line per diagnostic:

main.py:4:7: error[invalid-argument-type] Argument to function `greet` is incorrect: Expected `str`, found `Literal[42]`

Every diagnostic is severity[rule-name] — feed that rule name straight to ty explain rule. info-level diagnostics (like revealed-type) never affect the exit code.

Warnings fail the build by default (verified on 0.0.72). Three flags adjust this, and --error-on-warning is mutually exclusive with the other two:

• --exit-zero-on-warning — exit 1 only for error-level. This is what you want if warnings should be advisory.
• --error-on-warning — exit 1 for warning-or-higher (the current default, stated explicitly).
• --exit-zero — always exit 0; use to collect a report without failing.

CI recipe (GitHub Actions)

- uses: astral-sh/setup-uv@v6
- run: uv sync --dev
- run: uv run ty check --output-format github --exit-zero-on-warning

--output-format github emits ::error/::warning/::notice workflow annotations that surface inline on the PR diff. Use gitlab for Code Quality reports, junit for a JUnit XML artifact. Pin ty (uv add --dev ty, or uvx ty@0.0.72) so a patch release can't turn CI red overnight.

Coming from mypy or pyright

A ~90-row rule-to-report*/error-code mapping table lives in ty's own docs/coming-from-mypy-or-pyright.md; the practical subset plus ready-to-paste strictness configs are in references/mypy-pyright-migration.md.

Editors & the language server

ty server speaks LSP over stdio and provides completions, hover, go-to-definition, auto-import, inlay hints, code actions, and quick fixes, with fine-grained incremental recompute. Don't invoke it by hand — install the integration: the official VS Code extension (astral-sh.ty), Neovim via nvim-lspconfig (vim.lsp.enable('ty')), Zed, PyCharm, and Emacs are all covered in ty's docs/editors.md. The VS Code extension sets python.languageServer: "None" to avoid running two servers; set ty.disableLanguageServices: true to keep Pylance for IDE features and use ty only for type checking.

Troubleshooting

Recently changed (stale-knowledge traps)

Only the items where prior knowledge is likely wrong — verified against ty's CHANGELOG and the 0.0.72 binary:

References

• references/cli-reference.md — every command and flag, output formats, exit-code matrix, environment variables.
• references/configuration.md — all six config tables, every key and default, [[overrides]], discovery and precedence.
• references/rules-and-suppression.md — rule levels, looking rules up, the opt-in rules, full suppression semantics.
• references/mypy-pyright-migration.md — migration checklist, rule/error-code mapping, strictness configs.

Upstream: ty docs · repo · playground · rule catalog ty explain rule --output-format json.