ty type checker

published: August 21, 2025 •
pythontytype-checkingrustastralmypypyrightlanguage-server
on this page

tl;dr

Install:uvx ty check for quick start or uv add --dev ty
Speed:10-20x faster than mypy/pyright - rust implementation by astral
Status:Pre-alpha - not production ready, rapid development
Language server:VS Code extension, real-time type checking
Gradual:Minimal false positives, respects gradual typing
Integration:Works with uv - integrated astral toolchain

overview

ty - extremely fast python type checker and language server written in rust

  • created by astral (makers of ruff and uv)
  • performance focus: 10-20x faster than mypy, 2-5x faster than pyright
  • gradual typing friendly: minimal false positives on untyped code
  • integrated toolchain: works seamlessly with uv, ruff, and other astral tools
  • official docs

status and stability

⚠️ pre-alpha software (v0.0.1a19) - not production ready

  • many false positives in current releases
  • limited feature set compared to mature alternatives
  • rapid development cycle with frequent breaking changes
  • general availability targeted for late 2025

performance comparison

speed benchmarks (real-world codebases)

tool100k loc codebasepytorch codebasedjango 5.2.1
ty2.5 seconds0.5 seconds578ms
pyright13.6 seconds-16.3 seconds
mypy45+ seconds18 seconds60+ seconds

vs mypy vs pyright

ty advantages:

  • extreme performance: 10-20x faster than mypy
  • gradual guarantee: no new errors on working untyped code
  • rust implementation: leverages astral’s ruff infrastructure
  • incremental analysis: salsa-based caching for watch mode
  • modern design: built from scratch with 2025+ requirements

mypy advantages:

  • ecosystem maturity: extensive documentation and plugins
  • pep 484 reference: original static typing implementation
  • production stability: battle-tested on large codebases
  • configuration flexibility: extensive customization options

pyright advantages:

  • vs code integration: pylance provides excellent editor experience
  • typescript codebase: sophisticated type inference engine
  • language server features: completion, hover, refactoring
  • microsoft support: active development and maintenance

installation and quick start

assumes you have uv installed

quick start (no installation)

# check current project
uvx ty check

# check specific files
uvx ty check src/main.py src/utils.py

# watch mode for development
uvx ty check --watch

permanent installation

# project dependency (recommended)
uv add --dev ty

# global tool installation
uv tool install ty

# traditional pip
pip install ty

first run

# basic project check
ty check

# verbose output for debugging
ty check --verbose

# concise output for ci
ty check --output-format concise

configuration

basic pyproject.toml setup

[tool.ty.environment]
python-version = "3.11"
python = ".venv"  # virtual environment path

[tool.ty.rules]
# core safety rules (recommended)
unresolved-reference = "error"
invalid-assignment = "error"
invalid-argument-type = "error"
call-non-callable = "error"

# helpful warnings
deprecated = "warn"
redundant-cast = "warn"

# noise reduction
division-by-zero = "ignore"
possibly-unresolved-reference = "ignore"

[tool.ty.src]
include = ["src", "tests"]
exclude = ["src/generated/**", "build/**"]
respect-ignore-files = true

[tool.ty.terminal]
output-format = "full"  # or "concise"
error-on-warning = false

migration from mypy

[tool.ty.environment]
python-version = "3.11"
# use existing mypy search paths
extra-paths = ["src", "stubs", "vendor"]

[tool.ty.rules]
# mypy --strict equivalent
unresolved-reference = "error"
invalid-assignment = "error"
invalid-argument-type = "error"
invalid-return-type = "error"
missing-argument = "error"
unresolved-import = "error"

# gradual enablement
possibly-unresolved-reference = "warn"

migration from pyright

[tool.ty.environment]
python-version = "3.11"
root = ["src"]  # similar to pyright's include

[tool.ty.src]
exclude = ["tests/**", "build/**"]  # similar to pyright's exclude

[tool.ty.rules]
# pyright-like strictness
unresolved-reference = "error"
invalid-assignment = "error"
unresolved-attribute = "error"
call-non-callable = "error"
possibly-unbound-attribute = "warn"

per-directory overrides

# strict rules for core modules
[[tool.ty.overrides]]
include = ["src/core/**"]
[tool.ty.overrides.rules]
deprecated = "error"
possibly-unbound-attribute = "error"

# relaxed rules for tests
[[tool.ty.overrides]]
include = ["tests/**"]
[tool.ty.overrides.rules]
unresolved-reference = "warn"
missing-argument = "warn"

practical use cases

development workflow

# active development with watch mode
ty check --watch src/

# pre-commit hook integration
ty check --error-on-warning --output-format concise

# custom rule enforcement
ty check --error deprecated --warn redundant-cast

# performance profiling
TY_LOG_PROFILE=1 ty check

ci/cd integration

# github actions example
- name: type check
  run: |
    uv run ty check --error-on-warning --output-format concise

# with performance tuning
- name: type check (optimized)
  env:
    TY_MAX_PARALLELISM: 4
    RAYON_NUM_THREADS: 4
  run: uv run ty check --exit-zero

editor integration

vs code setup:

  1. install astral-sh.ty extension
  2. configure workspace settings:
{
  "ty.diagnosticMode": "workspace",
  "ty.inlayHints.variableTypes": true,
  "ty.inlayHints.callArgumentNames": true,
  "python.defaultInterpreterPath": "./.venv/bin/python"
}

neovim lsp configuration:

-- neovim 0.11+
vim.lsp.config('ty', {
  settings = {
    ty = {
      configFile = "./pyproject.toml"
    }
  }
})
vim.lsp.enable('ty')

gradual adoption strategy

week 1: zero false positives

[tool.ty.rules]
unresolved-reference = "error"
invalid-assignment = "error"
call-non-callable = "error"

week 2-3: function safety

[tool.ty.rules]
missing-argument = "error"
unknown-argument = "error"
invalid-argument-type = "warn"  # start as warning

month 2: full coverage

[tool.ty.rules]
invalid-argument-type = "error"  # promote to error
invalid-return-type = "error"
deprecated = "warn"
redundant-cast = "warn"

common pain points

false positives in pre-alpha

issue: ty reports many incorrect errors on valid code

# ty may incorrectly flag this as error
result = api_call()  # ty: ignore[unresolved-reference]

mitigation strategies:

  • start with minimal rule set
  • use --exit-zero for gradual adoption
  • suppress specific rules: # ty: ignore[rule-name]
  • monitor astral’s release notes for improvements

limited configuration options

issue: fewer config options compared to mypy/pyright

# ty currently lacks some advanced features
[tool.ty.rules]
# no per-module configuration like mypy
# no strict mode presets like pyright

workarounds:

  • use override sections for different strictness levels
  • combine with ruff for additional code quality checks
  • leverage .gitignore for file exclusions

ecosystem integration gaps

issue: limited plugin ecosystem compared to mature tools

current limitations:

  • no django-stubs equivalent integration
  • limited third-party type checker extensions
  • fewer ide integrations beyond vs code

advanced configuration

environment variables

# performance tuning
export TY_MAX_PARALLELISM=8
export RAYON_NUM_THREADS=8

# debugging and profiling
export TY_LOG="debug"
export TY_LOG_PROFILE="1"

# environment detection
export VIRTUAL_ENV="/path/to/venv"
export TY_CONFIG_FILE="./custom-ty.toml"

complete rule reference

error-level rules (60+ available):

[tool.ty.rules]
# type safety
invalid-assignment = "error"
invalid-argument-type = "error"
invalid-return-type = "error"
call-non-callable = "error"

# references and imports
unresolved-reference = "error"
unresolved-import = "error"
unresolved-attribute = "error"

# runtime errors
index-out-of-bounds = "error"
not-iterable = "error"
invalid-key = "error"

# function calls
missing-argument = "error"
unknown-argument = "error"
no-matching-overload = "error"

warning-level rules:

[tool.ty.rules]
deprecated = "warn"
redundant-cast = "warn"
possibly-unbound-attribute = "warn"
invalid-ignore-comment = "warn"

error suppression

# suppress specific rules
x = dynamic_value()  # ty: ignore[unresolved-reference]

# suppress multiple rules
result = complex_call()  # ty: ignore[missing-argument, invalid-argument-type]

# function-level suppression
from typing import no_type_check

@no_type_check
def legacy_function():
    # all type checking disabled
    pass

integration with astral toolchain

with uv package manager

# create project with ty
uv init my-project
cd my-project
uv add --dev ty

# integrated workflow
uv run ty check
uv run ruff check
uv run ruff format

with ruff linter

# pyproject.toml - coordinated configuration
[tool.ruff]
extend-select = ["typing-hints"]

[tool.ty.rules]
deprecated = "error"  # ty catches usage

docker integration

FROM ghcr.io/astral-sh/uv:latest as uv
FROM python:3.13-slim

# copy uv and install ty
COPY --from=uv /uv /uvx /bin/
RUN uv tool install ty

# type check during build
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project

COPY . .
RUN ty check --error-on-warning
RUN uv sync --frozen

CMD ["uv", "run", "python", "-m", "myapp"]

troubleshooting

module resolution issues

# debug environment detection
ty check --verbose

# explicit python environment
ty check --python .venv

# add missing search paths
ty check --extra-search-path ./stubs --extra-search-path ./vendor

performance optimization

[tool.ty.src]
# avoid expensive glob patterns
exclude = ["build/**"]     # good
# exclude = ["**/build/**"] # slower

# exclude large directories
exclude = ["node_modules/**", ".git/**", "**/.mypy_cache/**"]

editor integration troubleshooting

vs code issues:

  1. check extension installation: astral-sh.ty
  2. verify python interpreter: ctrl+shift+p → “python: select interpreter”
  3. check output panel for ty language server logs

general lsp issues:

# start language server manually for debugging
ty server --log-level debug --log-file ty.log

future roadmap

planned features (2025)

  • auto-import capabilities: intelligent import suggestions
  • go-to-definition: navigate to type definitions
  • completion improvements: better autocomplete integration
  • refactoring tools: rename symbols, extract methods
  • plugin ecosystem: extensibility for framework-specific rules

long-term vision

  • unified astral workflow: seamless uv → ruff → ty integration
  • shared type information: ruff lint rules powered by ty’s type analysis
  • performance leadership: maintain speed advantage as features expand
  • gradual typing advocacy: promote adoption through excellent ux

resources

related pages

more in programming

on this page