Skip to content

Type Checking

The handbook recommends Pyrefly (Meta) as the default type checker for new Python projects. mypy remains the established option, ty is Astral’s fast beta alternative, and pyright rounds out the field. These pages explain how each checker works, when to choose which, and how to adopt typing without rewriting your codebase.

Pick a type checker

Pyrefly reference
The handbook’s recommended default
ty vs Pyrefly
The two fast type checkers, head to head
mypy vs ty vs pyright
Three checkers, side by side
mypy reference
The established type checker

Adopt type checking

Gradual adoption
Add typing to a project that doesn’t have it
Migrate to Pyrefly
Move an existing mypy project to the default
mypy strict mode
Tighten the screws
Try ty
Run ty against your codebase

More Type Checking pages

Everything else tagged type-checking, grouped by section. Pages featured above are not repeated here.

Tutorial

Build and Publish a Python Package with uv, Ruff, Pyrefly, pytest, and GitHub Actions

Build a Python library with uv, Ruff, Pyrefly, and pytest. Set up CI/CD with GitHub Actions. Publish to PyPI with trusted publishing.

Set up a complete Python project with uv, Ruff, Pyrefly, pytest, and pre-commit

Tutorial: build a Python project from scratch with uv, Ruff, Pyrefly, pytest, and pre-commit. Set up linting, type checking, and testing.

Set up type checking for a Python project with ty

Add ty to a uv project, read its diagnostics, and tune rule levels so type mistakes surface before the code ever runs.

How To

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

Add type annotations to your Python project using pyrefly infer. Automatically generate parameter and return types from static code analysis.

How to configure Claude Code with a Python type checker

Integrate type checkers with Claude Code using CLAUDE.md, language-server plugins, Stop hooks, and pre-commit to surface errors during turns, not after.

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

Set up django-stubs and mypy in uv projects: configure the Django mypy plugin in pyproject.toml for legacy codebase type checking.

How to configure VS Code for type checking in a uv project

Set up type checking in VS Code for uv projects using ty or mypy extensions, including daemon mode and workspace diagnostics.

How to enforce annotation coverage on a Python library with Pyrefly

Track what fraction of your library's public API has type annotations and enforce a minimum threshold in CI with pyrefly coverage check.

How to migrate from mypy to ty

Migrate from mypy to ty for 9x faster type checking. Includes config mapping, compatibility guide, and plugin alternatives.

How to migrate from pyright to ty

Migrate from pyright to ty. Get faster type checking with no Node.js dependency and significantly simpler CI.

How to set up pre-commit hooks for a Python project

Install and configure pre-commit to automatically run linters, formatters, and checks on Git commits. Includes Ruff, mypy, and ty integration.

How to ship type annotations with a Python library

Add a py.typed marker and verify it ships in your wheel so your users' type checkers can read your annotations.

How to test a Python library against multiple type checkers

Test your library against mypy, Pyright, and Pyrefly to catch type errors across all common checkers before release.

How to Type-Check a Django Project with Pyrefly

Type-check a Django project with Pyrefly: install django-stubs, run the checker, and suppress unresolved errors.

How to use ty in CI

Set up ty type checking in GitHub Actions, GitLab CI, and other CI platforms with the right output format for inline annotations.

Explanation

Does Ruff support type checking?

No. Ruff is a linter and formatter; it does not perform type inference. Use ty, mypy, Pyright, or Pyrefly alongside Ruff for type checking.

How do Ruff and Pylint compare?

Ruff outpaces Pylint by orders of magnitude with auto-fix support; Pylint adds semantic depth Ruff doesn't cover yet.

How mypy, ty, and Pyrefly handle untyped code

mypy skips unannotated code by default; ty and Pyrefly infer and check it. This creates friction when migrating from mypy to stricter checkers.

Complete Guide to ty

A comprehensive guide to ty, the fast Python type checker from OpenAI. Learn installation, configuration, editor setup, and migration from mypy or pyright.

What is a Python language server?

A long-running process providing editors with autocomplete, hover docs, go-to-definition, and diagnostics. How they relate to type checkers.

What is PEP 484?

PEP 484: Python's optional type hints standard. Add type annotations for IDE autocomplete and type checker verification.

What is PEP 561?

PEP 561 defines how packages ship type info: py.typed markers for inline annotations, -stubs packages for separate types.

What is PEP 604?

PEP 604 lets Python 3.10+ write union types with the pipe operator: int | str replaces Union[int, str], and int | None replaces Optional[int].

What is PEP 612?

PEP 612 adds ParamSpec and Concatenate to Python's typing system so decorators can preserve the signatures of the functions they wrap.

What is PEP 649?

PEP 649: Deferred type annotations in Python 3.14. Avoid runtime errors from forward references and complex types.

What is PEP 681?

PEP 681's dataclass_transform marker tells type checkers a library's classes behave like dataclasses, eliminating the need for per-library checker plugins.

What is PEP 688?

PEP 688 types the buffer protocol. Learn why type checkers now reject bytearray where bytes is expected.

What is PEP 695?

PEP 695 adds Python 3.12 syntax for generics: class Box[T], def first[T], and type aliases without TypeVar or Generic base classes.

Reference

basedpyright

Basedpyright: pyright fork with Pylance editor features, PyPI distribution, stricter diagnostic rules, and no Node.js dependency.

pylint

Pylint: static analyzer catching errors beyond style linters—duplicate code, cyclomatic complexity, design issues.

pyright

Fast Python type checker from Microsoft with strong error detection. Integrates with VS Code through Pylance for immediate feedback.

ty

ty is a Python type checker from Astral (OpenAI). Features, configuration, IDE integration, and comparison to mypy and Pyright.

zuban

Zuban: Rust type checker with mypy and pyright modes, from Jedi's author. Fast performance, AGPL-3.0 or commercial license.

From the blog

Posts tagged type-checking.

Last updated on