ty: Astral's Rust-based Python type checker and language server

What ty checks, and who is expected to run it

ty is a type checker for Python code and a language server that speaks the same analysis to your editor. The README describes it as "An extremely fast Python type checker and language server, written in Rust" and states it is backed by Astral, the company behind uv and Ruff. That lineage matters for positioning: this is not a research checker, it is a tool intended to sit in the same workflow as uv and Ruff.

The stated audience is broad. The README lists "Designed for adoption, with support for redeclarations and partially typed code" as a highlight, and the classifiers in pyproject.toml include "Development Status :: 4 - Beta" and "Intended Audience :: Developers". A codebase that is fully annotated and a codebase that is mostly unannotated are both in scope, which is unusual for a checker that also advertises advanced typing features.

The performance claim in the README is "10x - 100x faster than mypy and Pyright", illustrated by a benchmark chart of type checking the home-assistant project without caching. That is a claim from the project, not a measurement anyone else has reproduced here. Treat it as the project's own comparison, and run it against your own tree if the number is what decides the adoption.

How ty analyses code: incremental, gradual, and rule-configurable

The mechanism visible from the repository is a Rust binary with a Python packaging layer. pyproject.toml declares name = "ty", version = "0.0.82", requires-python = ">=3.8", an empty dependencies list, and a maturin build backend, so the distributed artifact is a compiled extension or binary rather than a pure-Python package. The Dockerfile confirms the shape: it builds with cargo zigbuild --bin ty and produces a single binary at /ty with ENTRYPOINT ["/ty"].

On the analysis side, the README points at several distinct features rather than one monolithic mode. Diagnostics are described as comprehensive with contextual information. Rule levels, per-file overrides and suppression comments are configurable, which means the checker's output is meant to be tuned per project rather than accepted wholesale. The type system page covers redeclarations, a gradual guarantee for partially typed code, intersection types, type narrowing, and reachability analysis based on types.

The language server is the second half of the design. The README lists code navigation, completions, code actions, auto-import, inlay hints and on-hover help, and describes "fine-grained incremental analysis" for fast updates while editing. That is a different engineering problem from batch checking: the server has to recompute a small slice of the program on each keystroke rather than reanalyse everything. The repository layout reflects the split, with a python/ directory alongside the Rust sources, a ruff submodule, and a docs/ tree built with mkdocs.yml.

Installing ty and running a first check

The README's getting-started path does not require an install step at all. It gives one command, using uvx, which runs a tool without adding it to a project environment:

uvx ty check

Run that from the root of a Python project. The reader should see ty report type errors for the files it discovers, or exit quietly on a clean tree. The README also points at a browser playground at play.ty.dev for trying the checker without a local install.

For a persistent installation, the README does not inline the commands. It says: "To install ty, see the installation documentation", linking to docs.astral.sh/ty/installation/. That page is the authority for the standalone installer, the PyPI package and any platform-specific steps; the README itself only commits to the uvx path. The FAQ adds one relevant constraint: ty installed from PyPI needs Python 3.8 or later, while "the standalone installer does not require Python at all".

Editor setup follows the same pattern. The README links to an editor integration guide rather than embedding config, and lists VS Code, PyCharm and Neovim among the integrations. If the language server is the reason you are evaluating ty, read that guide before the CLI docs, because the server and the CLI are configured as separate concerns.

The beta contract: 0.0.x versioning and shifting diagnostics

The most consequential thing about ty right now is its version policy, and the README states it plainly. ty uses 0.0.x versioning, has no stable API yet, and "breaking changes, including changes to diagnostics, may occur between any two versions".

That is a stronger caveat than the word beta usually implies. A change to diagnostics is not an internal refactor; it can turn a passing CI run red, or turn a red run green, without any change in your own code. A team that pins ty and gates merges on its exit code is pinning a moving target. The mitigation is to pin an exact version and upgrade deliberately, but the README does not document a stability window or a deprecation process for diagnostics, so there is nothing to plan against beyond reading the changelog.

The project does publish a Stable milestone and a type system support tracking issue, which the README references for the current feature overview. Those are the places to check what is actually implemented, because the highlights list describes capabilities the checker aims at, not a completeness guarantee. For a checker whose value is catching errors before runtime, the gap between advertised and implemented typing features is the number that matters, and it is not in the README.

Python version support and where ty will mislead you

The FAQ sets the support boundary: ty officially supports type checking code that targets Python 3.10 and later. Python 3.7 through 3.9 can still be selected as a target, but the FAQ warns this "may result in false negatives or false positives due to a lack of bundled standard library stubs".

This is the clearest case where ty is the wrong tool, or at least a risky one. If your project still targets 3.9, you can point ty at it, but the checker's answers about standard library types are not trustworthy, and a false negative is worse than no check at all because it manufactures confidence. The target version is decoupled from the interpreter running ty, so the fact that ty installs cleanly on an old Python does not mean it checks old-Python code correctly.

The second limitation is the beta status itself. There is no stable API, and the README does not document rollback behaviour, a compatibility matrix between versions, or how suppression comments survive a diagnostics change. A suppression comment written against one version's rule set may become unnecessary or misdirected in the next. Teams that need a checker whose output is a fixed contract should wait for the Stable milestone rather than adopt now.

ty against mypy and Pyright

The README's own comparison target is mypy and Pyright, with the 10x to 100x speed claim. The difference in approach is implementation language and execution model: ty is written in Rust and ships as a compiled binary, while mypy is a Python program and Pyright is a TypeScript program running on Node. That distinction is what the benchmark chart is measuring, and it is why the project leads with speed rather than with type system completeness.

The trade-off is maturity, and it runs the other way. mypy and Pyright have years of accumulated behaviour and stable release lines behind them; ty is at 0.0.82 with an explicit warning that diagnostics can change between any two versions. A team migrating a large annotated codebase to ty should expect to re-triage errors that the previous checker did not report, and to re-triage them again after an upgrade. The README's adoption features (redeclarations, partially typed code) are aimed at reducing that friction, but they do not remove it.

One more comparison lives in the search data rather than the README: people ask whether ty or Pyrefly is the better type checker. Nothing in the repository describes Pyrefly, so there is no basis for a verdict. The honest answer is that ty's published differentiators are speed, the Astral toolchain, and the language server, and that any head-to-head depends on which typing features your codebase actually uses.

Licence, maintenance and the cost of upgrading

ty is MIT licensed. The README states the licence and adds the standard contribution clause: contributions intentionally submitted for inclusion are licensed under the same terms unless stated otherwise. MIT is permissive, so redistribution and commercial use are not restricted by the licence itself; the repository's LICENSE file is the controlling text, and this is not legal advice.

The repository is not archived, and the last push was on 2026-09-18, three days before this writing. Releases are frequent and tightly spaced: 0.0.82 on 2026-09-17, 0.0.81 on 2026-09-15, 0.0.80 on 2026-09-09. That cadence is the maintenance story, and it is also the upgrade cost. Frequent 0.0.x releases with no stable API mean upgrades are a recurring task rather than a rare one, and the changelog is the only way to know whether a given release changes diagnostics you depend on.

One structural detail affects contribution and, indirectly, how fast fixes land: the README says development takes place in the Ruff repository, and changes to the ruff submodule, which includes all of the Rust source code, should be opened as pull requests there. So the ty repository is not where the implementation lives. Anyone planning to patch a diagnostic or send a fix needs to work in Ruff, not here.

Editorial conclusion

Adopt ty if you want a fast checker and editor server from the Astral toolchain and can tolerate 0.0.x churn; do not adopt it if you need a frozen diagnostic set for CI gating or you target Python 3.9 or earlier. Before committing, run uvx ty check on your own repository and read the type system support tracking issue.

Frequently asked questions

Official sources

1. astral-sh/ty on GitHub
2. License: MIT
3. Project website
4. README
5. Releases