ty review
ty is Astral's Rust-written Python type checker and language server. The CLI checks a project, watches affected files, emits terminal, GitHub, or JUnit diagnostics, and lets teams set rule severity globally or per file. Its editor server adds navigation, completion, code actions, auto-imports, hover information, and incremental analysis. Version 0.0.74 fixes crashes and incorrect handling around string annotations and recursive TypedDicts, adds an `untrustedWorkspace` LSP option, supports notebook pull diagnostics, and introduces an opt-in unsound-assignment rule. It remains beta with no stable diagnostic contract.
ty is easy to trial because our measured wheel installed as one 1 MB package and the CLI can run beside an existing checker. Keep that parallel run until its beta diagnostics, target-version coverage, and results on your own code are good enough to pin in CI.
We installed it
| Install | ✓ · 0.3s | 1 package on disk · 1 MB |
| Import | ✓ | import ty in 0.04s · compiled extensions · py.typed · requires Python >=3.8 |
| Known vulns | 0 | (pip-audit) |
Answers from our run
Does ty install cleanly?
Yes. In a fresh container with an empty cache, pip install ty finished in 0.3s, leaving 1 package and 1 MB on disk. pip-audit reported no known vulnerabilities.
What does ty need to run?
Python >=3.8, and a platform wheel with compiled extensions. In our run import ty succeeded in 0.04s, and the package ships py.typed for type checkers.
ty or mypy: which should you use?
mypy: Use it for a long-established checker with a large plugin ecosystem and familiar gradual-typing behavior. ty is easy to trial because our measured wheel installed as one 1 MB package and the CLI can run beside an existing checker.
When should you not use ty?
Your CI requires stable diagnostics across patch upgrades; ty uses 0.0.x versioning and its README permits breaking changes between any two releases
Use it if
- A Python repository wants a very fast local type-check loop and can compare results with its current checker during adoption
- One tool should provide both CI diagnostics and a language server with incremental editor feedback
- Rule severities, per-file overrides, targeted suppression comments, project roots, and environment discovery need first-class configuration
- The code targets Python 3.10 or newer, which is the range Astral officially supports for accurate checking
- Your CI requires stable diagnostics across patch upgrades; ty uses 0.0.x versioning and its README permits breaking changes between any two releases
- The project targets Python 3.7 through 3.9 and cannot accept false positives or negatives; those targets can be selected but are outside official checking support
- Your codebase depends on mypy plugins, Pyright-specific configuration, or a corner of Python's type system that ty's published support tracker has not completed
- You need a pure-Python tool or an unsupported CPU and operating-system combination; the PyPI package ships compiled native code and wheel availability matters
- The team plans to replace its existing checker in one step without a baseline; different inference and rule defaults can hide old findings while introducing new ones
Setup reality
We installed ty 0.0.73 in a fresh Python 3.12 Bookworm container. The install completed in 0.3 seconds, left one package, and used 1 MB. pip-audit found no known vulnerabilities. Package metadata lists zero direct dependencies, Python 3.8 or newer, and the MIT License. The wheel ships compiled .so code plus a py.typed marker. import ty worked in 0.04 seconds. The current registry version is 0.0.74, so the measured install is one patch behind the guide's release metadata.
Run ty check from a project or pass paths explicitly. ty finds pyproject.toml, a nearby virtual environment, and Python requirements, but monorepos and unusual environments should set the project root and interpreter deliberately. The install-time Python floor is 3.8; the checked code's target version is separate. Astral officially supports checking Python 3.10 and newer, even though earlier targets can be selected. Pin python-version and python-platform so a developer laptop and Linux CI do not resolve conditional stubs differently.
Configuration can live under [tool.ty] in pyproject.toml or in a dedicated ty.toml with the shorter section names. Set project roots and exclusions before tuning rules. ty respects common ignore files by default, which can surprise a repository that expects generated or vendored code to be checked. It resolves third-party imports from the selected Python environment. Point environment.python or --python at the real virtual environment instead of silencing every unresolved import.
Adopt ty beside the existing checker first. Record both result sets, fix clear bugs, and add narrow # ty: ignore[rule-name] comments only where the difference is understood. Blanket # type: ignore comments may affect more than one checker. In CI, use --output-format github for annotations or JUnit for report ingestion, and decide whether warnings should fail with --error-on-warning. Version 0.0.74 adds LSP handling for untrusted workspaces; editor administrators should still review what executable the extension discovers and starts.
Patterns
Check the discovered project check-project
ty checkRun from the project directory. ty searches upward for project configuration and discovers a nearby Python environment.
Limit checking to selected paths check-paths
ty check src testsExplicit paths narrow the command, but imports outside them may still be analyzed to resolve types.
Recheck after file changes watch-project
ty check --watchWatch mode uses incremental analysis and rechecks files related to the changed path.
Pin the checked Python version set-target-python
[tool.ty.environment]
python-version = "3.12"
python-platform = "linux"The target controls syntax and conditional type definitions. It is independent of the Python version used to install ty.
Point ty at a virtual environment select-environment
[tool.ty.environment]
python = "./.venv"Use the environment that contains project dependencies so third-party imports resolve against the right packages and stubs.
Declare import roots for a monorepo set-project-roots
[tool.ty.environment]
root = ["./services/api/src", "./packages/shared/src"]
extra-paths = ["./generated"]Root order affects first-party module resolution. Keep generated paths explicit instead of broadening unresolved-import allowances.
Change rule severities configure-rules
[tool.ty.rules]
possibly-unresolved-reference = "warn"
division-by-zero = "error"Rule names are part of beta diagnostics and can change. Review configuration when updating ty.
Relax one rule only in tests override-test-rules
[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]
[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"Later matching overrides take precedence. Keep the scope narrow so production modules retain the global severity.
Suppress one finding on one line suppress-diagnostic
total = price + label # ty: ignore[unsupported-operator]Name the rule instead of using a blanket ignore, and leave a code comment when the reason is not obvious.
Emit GitHub Actions annotations annotate-github
ty check --output-format github --error-on-warningThis format creates workflow annotations. The warning flag makes warning-level diagnostics return a failing exit status.
Produce JUnit diagnostic output write-junit-report
ty check --output-format junit > ty-report.xmlThe shell writes XML to the report file. Preserve ty's process exit code separately if the CI wrapper masks it.
Read the explanation for a rule explain-rule
ty explain invalid-argument-typeUse the reported rule name from a diagnostic. Explanations help decide whether to fix, downgrade, or suppress the finding.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| mypy | PyPI | Use it for a long-established checker with a large plugin ecosystem and familiar gradual-typing behavior |
| pyright | PyPI | Use it for mature editor integration, strict modes, and the type engine behind Pylance |
| pyrefly | PyPI | Use it when evaluating another native-speed checker and language server with different inference choices |
More cli & tooling guides
chalk · commander · typescript · esbuild · yargs · click · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.