Python Developer Tooling Handbook – Type Checking

ty: A Complete Guide to Python's Fastest Type Checker

Tim Hopper — Fri, 15 May 2026 11:47:17 -0400

ty is a Python type checker and language server built by Astral, the team behind Ruff and uv. It checks Python code for type errors an order of magnitude faster than mypy. The same binary that runs ty check in CI also serves as a full language server, powering editor features like completions and go-to-definition.

Why ty exists

ty’s gradual guarantee makes incremental type adoption safe: adding annotations to your code will never introduce new errors. You can annotate a function’s return type and ty won’t flag callers that were already passing the wrong type just because the annotation appeared. Each annotation only narrows existing errors rather than creating new ones.

Basedpyright: Python Type Checker (pyright Fork)

Tim Hopper — Fri, 15 May 2026 11:47:17 -0400

Basedpyright is a static type checker and language server for Python, maintained by DetachHead as a community fork of Microsoft’s pyright. It tracks upstream pyright closely and adds diagnostic rules, stricter defaults, and language-server features that Microsoft keeps exclusive to its closed-source Pylance extension.

The fork exists because pyright ships as an npm package and depends on Node.js, which makes it awkward to pin as a project dependency, and because the editor features most Python developers associate with “pyright” actually live in Pylance, whose license restricts it to official Microsoft VS Code builds. Basedpyright packages the language server on PyPI so uv add --dev basedpyright works, and re-implements Pylance-style features (inlay hints, semantic highlighting, docstring completion) in the open-source server so VS Code forks like Cursor, VSCodium, and Positron can use them.

How do Python type checkers compare?

Tim Hopper — Fri, 15 May 2026 22:53:52 -0400

mypy, pyright, ty, Pyrefly, Basedpyright, and Zuban all analyze type annotations to catch bugs before runtime. They read the same type-hint annotations (from PEP 484, the standard that introduced Python’s type system in 2014) and largely agree on the parts of the spec a working program uses. They disagree on speed, default strictness, treatment of unannotated code, editor integration, and licensing, and those disagreements are what make the choice matter.

The handbook recommends Pyrefly (Meta) as the default for new projects. See When to choose each for the rationale and the cases where a different checker fits better.

How to add type annotations to a Python project with pyrefly infer

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Pyrefly can turn def total(numbers): into def total(numbers: list[int]) -> int: without running your code. The command is pyrefly infer, previously called autotype, and it writes draft annotations by reading call sites with static analysis.

For a legacy codebase with thousands of unannotated functions, this turns weeks of manual annotation into a reviewable diff. The output needs a human review pass before merging.

Note

How to configure Claude Code with a Python type checker

Tim Hopper — Fri, 15 May 2026 21:28:17 -0400

Claude Code does not run a Python type checker by default, and the gap is wider than it looks. Listing uv run ty check in CLAUDE.md looks like enough configuration, but Pyrefly’s documented agentic-loop pattern shows that models routinely skip the command unless the type checker is wrapped in a loop that runs after every edit. With the wrapper in place, the model engages with errors; without it, the model treats the checker as optional.

How to configure mypy and django-stubs in a uv project

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Run mypy on a Django project without django-stubs and the first error is Need type annotation for "name" on every model field. mypy cannot infer that models.CharField(max_length=200) resolves to str or that Question.objects.filter() returns a QuerySet[Question]. The django-stubs package and its bundled mypy plugin fill those gaps.

This guide installs both with uv and configures everything from a single pyproject.toml, with an override pattern for adopting type checking gradually on a legacy Django codebase.

How to configure mypy strict mode

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

This guide assumes you have a Python project set up with uv and mypy installed as a dev dependency.

Running mypy with default settings is lenient. It skips function bodies that lack type annotations and ignores several categories of type errors. Strict mode closes these gaps by requiring annotations on all functions and enabling a curated set of optional checks. The exact flags included in --strict may change between mypy releases.

How to gradually adopt type checking in an existing Python project

Tim Hopper — Sat, 16 May 2026 06:16:22 -0400

This guide assumes you have a Python project managed by uv. If you haven’t created a project yet, see the project creation tutorial before proceeding.

Running a type checker on an established codebase for the first time produces hundreds or thousands of errors. That wall of red discourages adoption before it starts. The practical path is to check new code strictly while ignoring legacy issues, then shrink the ignore list over time.

How to migrate from mypy to Pyrefly

Tim Hopper — Wed, 13 May 2026 18:09:04 -0400

Pyrefly 1.0 ships an auto-migration tool that reads an existing mypy config and writes the equivalent Pyrefly configuration. The mechanical translation is one command. The diagnostic triage that follows is the real work, and Pyrefly’s incremental-adoption tooling makes it possible to do that work without blocking CI.

This guide walks through both halves using pre-commit as a real example.

Confirm your mypy config location

pyrefly init reads two file formats:

How to migrate from mypy to ty

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

ty is a fast Python type checker, developed by Astral (the creators of uv and Ruff). It runs faster than mypy, especially on large codebases.

ty is currently in beta. While actively developed, it’s still missing some features and may not be ready for full production adoption. This guide helps evaluate readiness and plan for migration.

Understanding ty

When to consider migrating

Projects needing faster type checking on large codebases
Teams already using other Astral tools (Ruff, uv)
Projects not relying on mypy plugins

When to wait

Projects requiring Pydantic, Django, or SQLAlchemy mypy plugins
Projects requiring mature, battle-tested tooling

Installation and basic usage

Installing ty

ty is distributed as a standalone binary. The easiest way to use it is via uvx:

How to migrate from pyright to ty

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

ty is a Python type checker developed by Astral (the creators of uv and Ruff). It ships as a single binary with no runtime dependencies, which eliminates pyright’s Node.js requirement.

ty is currently in beta. While actively developed, it’s still missing some features and may not be ready for full production adoption. This guide helps evaluate readiness and plan for migration.

Understanding ty

When to consider migrating

Projects wanting faster type checking on large codebases
Teams already using other Astral tools (Ruff, uv)
Projects wanting to eliminate Node.js dependency
Projects without complex platform-specific dependencies lacking stubs
Projects with simple pyright configuration

When to wait

Projects heavily dependent on pyright-specific features like --verifytypes
Projects requiring typeCheckingMode presets (until ty adds equivalents)
Projects with complex platform-specific dependencies lacking stubs
Projects where pyright’s specific type inference is depended upon

Installation and basic usage

Installing ty

ty is distributed as a standalone binary. The easiest way to use it is via uvx:

How to try the ty type checker

Tim Hopper — Sat, 16 May 2026 06:16:22 -0400

This guide shows you how to try out ty, a static type checker and language server, in your project.

Looking to migrate from mypy to ty? See How to migrate from mypy to ty for detailed guidance.

Prerequisites

To proceed, you’ll need uv.

How to use ty in CI

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

ty can run in CI with no installation step beyond uv. Because ty is a single binary with no runtime dependencies, it adds minimal overhead to your pipeline.

GitHub Actions

The simplest approach uses uvx to run ty without adding it as a project dependency:

- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v7
- run: uvx ty check src/

To get inline annotations on pull requests, use the github output format:

mypy: Python Static Type Checker

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

mypy is a static type checker for Python that analyzes type annotations to detect bugs before runtime. It has been the default Python type checker since 2012 and has the broadest ecosystem support of any Python type checking tool.

When to use mypy

Use mypy when you want to catch type-related bugs before runtime by adding static type checking to a Python project. It is the most established Python type checker with broad ecosystem support, making it a reliable default for projects that are adopting type annotations incrementally. For faster checking or tighter VS Code integration, consider pyright; for an emerging alternative from the creators of Ruff, see ty.

pylint: Python Static Code Analyzer

Tim Hopper — Mon, 11 May 2026 06:30:40 -0400

Pylint is a static analysis tool for Python. It parses source code without executing it and reports coding-standard violations, suspicious constructs, and design-level issues such as overly complex functions and duplicate code blocks.

When to use pylint

Pylint suits codebases that already depend on its semantic checks: duplicate-code detection across modules and design-rule enforcement that style-focused linters do not cover. Teams with an established .pylintrc and a CI pipeline tuned around its output keep a familiar tool backed by a long-running plugin ecosystem.

Pyrefly: Python Type Checker by Meta

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

Pyrefly is a static type checker and language server for Python, developed by Meta. It performs static analysis on Python code to identify type-related issues before runtime and provides IDE features like code navigation, autocompletion, and semantic highlighting.

Pyrefly is a clean-slate implementation inspired by Meta’s earlier Pyre type checker. It uses a new type inference engine, a custom incremental computation model, and multi-threaded parallel checking.

When to use Pyrefly

Pyrefly is the handbook’s recommended type checker for new Python projects. It reached stable 1.0.0 in May 2026, runs 10-50x faster than mypy and pyright on large codebases, scores higher than ty and mypy on the typing-spec conformance suite (over 90% per the 1.0.0 release notes; see the Python typing conformance dashboard for live numbers), and ships first-party documentation for AI-agent workflows (skill files and Stop-event hooks). It checks aggressively, catching errors in unannotated code that mypy skips by default. Meta deploys Pyrefly on Instagram (~20M LOC), with adoption at PyTorch and JAX.

pyright: Python Static Type Checker by Microsoft

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

pyright is a static type checker and language server for Python, built and maintained by Microsoft. It analyzes type annotations to detect bugs before runtime and provides editor features like autocompletion, hover information, and go-to-definition.

pyright powers the Pylance extension for Visual Studio Code. Pylance is closed-source and adds features on top of pyright’s open-source language server, but pyright itself can be used with any editor that supports LSP.

When to use pyright

pyright is a strong choice for teams that want real-time type feedback in their editor, especially in VS Code through the Pylance extension. Its aggressive type inference catches bugs in unannotated code that mypy would skip by default.

ty: Python Type Checker by Astral

Tim Hopper — Sat, 16 May 2026 07:30:29 -0400

ty (pronounced tee-why) is a static type checker and language server for Python from Astral (creators of Ruff and uv). It performs static analysis on Python code to identify type-related issues before runtime.

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.

When to use ty

ty is an alternative to the handbook’s recommended type checker, Pyrefly. 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 and pyright and pairs cleanly with Ruff and uv in the Astral 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 Astral-toolchain coherence is a priority. For a full comparison across all major type checkers, see How do Python type checkers compare?.

What is a Python language server?

Tim Hopper — Tue, 05 May 2026 06:56:59 -0400

Type a dot after a variable in your editor and a list of methods appears. Hover a function and its signature shows up in a tooltip. Right-click an import and “Go to definition” jumps to the source. Most Python developers have used these features for years without knowing the name of the program behind them.

That program is a language server. It is a separate process running alongside your editor, and it is doing most of the work readers usually credit to “the editor.” Naming it explains why VS Code, Neovim, Cursor, and Zed give you the same autocomplete on the same file, and why a faster type checker makes your editor feel faster.

Zuban: Mypy-Compatible Python Type Checker

Tim Hopper — Fri, 15 May 2026 21:28:17 -0400

Zuban is a static type checker and language server for Python, written in Rust by David Halter, author of Jedi (the longstanding Python autocompletion library) and parso. It runs in two modes: zuban mypy (aliased as zmypy) behaves as a mypy-compatible drop-in, and zuban check applies a pyright-style inference strategy.

Zuban launched as open source under AGPL-3.0 in September 2025, with a paid commercial license available for organizations that cannot accept AGPL’s source-disclosure requirements. That licensing split is what most distinguishes Zuban from its competitors: it funds full-time development in a way that MIT-licensed alternatives cannot, but it also rules Zuban out for many proprietary codebases unless the team buys a commercial license.