# ty: Python Type Checker by OpenAI

ty (pronounced _tee-why_) is a static type checker and language server for Python from Astral, the creators of [Ruff](https://pydevtools.com/handbook/reference/ruff.md) and [uv](https://pydevtools.com/handbook/reference/uv.md), now part of OpenAI. It performs static analysis on Python code to identify type-related issues before runtime.

{{< callout type="info" >}}
ty was initially known by the code name "Red-Knot" during its early development phase. The tool is in beta, with a stable 1.0 release targeted for 2026.
{{< /callout >}}

## When to use ty

ty is an alternative to the handbook's recommended type checker, [Pyrefly](https://pydevtools.com/handbook/reference/pyrefly.md). Its "gradual guarantee" ensures that adding type annotations to working code never introduces new errors, which makes incremental adoption predictable in a partially-typed codebase. ty also runs 10-100x faster than [mypy](https://pydevtools.com/handbook/reference/mypy.md) and [pyright](https://pydevtools.com/handbook/reference/pyright.md) and pairs cleanly with [Ruff](https://pydevtools.com/handbook/reference/ruff.md) and [uv](https://pydevtools.com/handbook/reference/uv.md) in the OpenAI toolchain. Pyrefly is recommended over ty for most new projects because ty is still in beta as of 2026 and its typing-spec conformance trails Pyrefly's; choose ty if the gradual guarantee matters more than feature completeness, or if OpenAI-toolchain coherence is a priority. For a full comparison across all major type checkers, see [How do Python type checkers compare?](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare.md).

## Key Features

*   Performance: significantly faster than mypy and pyright (roughly 7x faster than mypy on typical codebases). Fine-grained incremental analysis provides near-instant feedback in an IDE.
*   Diagnostics: Detailed error messages with code-span annotations and rich contextual information.
*   Language Server: Full LSP implementation with go-to-definition, go-to-declaration, go-to-type-definition, find references, completions with auto-import, rename refactoring, inlay hints, hover, signature help, quick fixes, semantic highlighting, and code folding.
*   Configurable Rules: Each diagnostic rule can be set to error, warn, or ignore. Supports per-file overrides and suppression comments.
*   Gradual Guarantee: Adding type annotations to working code never introduces new errors. Annotations only narrow existing errors, which makes incremental adoption predictable.
*   Advanced Type System: First-class intersection types, type narrowing (including `hasattr` narrowing), and reachability analysis based on type inference.
*   Notebook Support: Language server features for Jupyter notebooks with cross-cell analysis.

## Type System Features

ty implements several type system features beyond what other type checkers provide:

*   Redeclarations: Allows reusing the same symbol with a different type within a function scope.
*   Intersection Types: First-class support for intersection types (`A & B`), which enables more precise type narrowing after `isinstance` checks.
*   Reachability Analysis: Uses type inference to detect unreachable branches, which can handle version-specific code paths for libraries like pydantic.
*   Fixpoint Iteration: Infers types for symbols that cyclically depend on themselves by iterating until the type converges.

## Installation

The quickest way to run ty is with [uvx](https://docs.astral.sh/uv/guides/tools/):

```shell
uvx ty check
```

For project use, add ty as a development dependency:

```shell
uv add --dev ty
uv run ty check
```

ty can also be installed globally with `uv tool install ty`, via pip, pipx, or using standalone installers available for macOS, Linux, and Windows.

## Basic Usage

```shell
# Check the current project
ty check

# Check specific files
ty check src/main.py

# Check with a specific Python version target
ty check --python-version 3.12

# Get an explanation of a specific rule
ty explain rule <rule-name>

# Show all rules
ty explain rule
```

## Configuration

ty reads configuration from `pyproject.toml` (under `[tool.ty]`) or a dedicated `ty.toml` file. Rule levels and other settings can be configured per-project:

```toml
[tool.ty.rules]
unused-ignore-comment = "warn"
possibly-missing-import = "error"
```

User-level configuration is also supported at `~/.config/ty/ty.toml`.

## Editor Integration

ty includes official editor support:

*   VS Code: Install the [ty extension](https://marketplace.visualstudio.com/items?itemName=astral-sh.ty) from the VS Code Marketplace.
*   Neovim: Configure via `nvim-lspconfig` or the built-in `vim.lsp.config` (Neovim 0.11+).
*   Zed: Built-in support (can be enabled in settings).
*   PyCharm: Native support starting with version 2025.3.
*   Emacs: Compatible via the built-in Eglot client (Emacs 29+).

For other editors, run `ty server` to start the language server.

## Comparison to Other Tools

ty is not a drop-in replacement for [mypy](https://pydevtools.com/handbook/reference/mypy.md) or [pyright](https://pydevtools.com/handbook/reference/pyright.md). It makes different design choices and has different default behaviors. The primary differentiators are speed (roughly 7x faster than mypy on typical codebases, with the gap varying by code patterns) and a gradual guarantee that adding annotations to working code never introduces new errors. ty checks all code by default, including unannotated function bodies that mypy skips, so a mypy-clean codebase can surface many new errors when first checked with ty. ty aims for conformance with the Python typing specification.

{{< callout type="warning" >}}
ty is in beta. Some features may be missing or behave differently compared to mature type checkers. Check the [tracking issue](https://github.com/astral-sh/ty/issues/1889) for type system feature status.
{{< /callout >}}

## Learn More

* [ty: A Complete Guide](https://pydevtools.com/handbook/explanation/ty-complete-guide.md)
* [How do mypy, pyright, and ty compare?](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare.md)
* [How to try the ty type checker](https://pydevtools.com/handbook/how-to/how-to-try-the-ty-type-checker.md)
* [How to migrate from mypy to ty](https://pydevtools.com/handbook/how-to/how-to-migrate-from-mypy-to-ty.md)
* [How to migrate from pyright to ty](https://pydevtools.com/handbook/how-to/how-to-migrate-from-pyright-to-ty.md)
* [How to use ty in CI](https://pydevtools.com/handbook/how-to/how-to-use-ty-in-ci.md)
* [How to gradually adopt type checking in an existing Python project](https://pydevtools.com/handbook/how-to/how-to-gradually-adopt-type-checking-in-an-existing-python-project.md)
* [How to configure Claude Code with a Python type checker](https://pydevtools.com/handbook/how-to/how-to-configure-claude-code-with-a-python-type-checker.md)
* [ty Documentation](https://docs.astral.sh/ty/)
* [ty Playground](https://play.ty.dev)
* [ty GitHub Repository](https://github.com/astral-sh/ty)