Skip to content

Pyrefly: Python Type Checker by Meta

by Tim Hopper
Type Checking

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.

Its conformance is lower than pyright and Zuban (another Rust-based checker); both remain reasonable alternatives where their specific advantages matter.

For a comparison of all major type checkers, see How do mypy, pyright, and ty compare?.

Key Features

  • Performance: checks over 1.85 million lines of code per second. Meta reports checking Instagram’s 20-million-line codebase in roughly 30 seconds.
  • Aggressive type inference: infers types of variables and return types without annotations. Unlike ty’s gradual guarantee approach, Pyrefly reveals concrete unions and catches errors like None * 2 even in unannotated code.
  • Flow types: refines static types through control flow analysis, narrowing types after guards and checks.
  • Framework support: built-in Pydantic support (model validation, field autocomplete) and Django integration (model field type awareness).
  • Tensor shape types (experimental): tracks PyTorch tensor dimensions through Dim[N] and Tensor[*Shape] annotations and surfaces inferred shapes as IDE inlay hints. See the Pyrefly tensor shapes tutorial.
  • Auto-annotation tool: pyrefly infer writes type annotations directly into source files for parameters, return types, container element types, and the imports they require. See how to add type annotations with pyrefly infer.
  • Module-level incrementality: rechecks only modules that changed, with optimized parallel checking across available cores.
  • Language server: full LSP implementation with code navigation, semantic highlighting, code completion, and inline documentation.
  • Typing spec conformance: Pyrefly 1.0.0 passes over 90% of the official Python typing conformance test suite, ahead of mypy and ty, behind pyright and Zuban. See the Python typing conformance dashboard for current numbers.
  • Auto-migration: pyrefly init reads existing mypy or pyright configuration and writes an equivalent Pyrefly config, or synthesizes one in-memory when no pyrefly.toml is present.
  • Adoption tooling: pyrefly report emits annotation-completeness metrics as JSON, and baseline files (experimental) snapshot existing errors so only new ones are surfaced.

Pros

  • Faster than mypy and pyright by 10-50x on large codebases
  • Higher typing spec conformance than mypy and ty
  • Aggressive inference catches bugs in unannotated code without requiring explicit annotations
  • pyrefly init auto-migrates existing mypy or pyright configuration
  • Stable 1.0.0 release with a published monthly release cadence
  • Cross-platform: macOS, Linux, and Windows (including ARM64)
  • MIT licensed

Cons

  • Lower conformance than pyright and Zuban on the official typing conformance suite
  • Tensor-shape checking for PyTorch is still experimental

Installation and Usage 

# Install with pip or uv
pip install pyrefly
uv pip install pyrefly

# Initialize configuration
pyrefly init

# Check a project
pyrefly check

# Run without installing
uvx pyrefly check

Pyrefly reads configuration from a [tool.pyrefly] table in pyproject.toml or from a standalone pyrefly.toml file. Both forms are first-class and accept the same options (see the configuration docs). pyrefly init generates a starter config and, when an existing mypy or pyright config is present, migrates its settings into Pyrefly’s format.

To add Pyrefly as a development dependency in a uv project:

uv add --dev pyrefly
uv run pyrefly check

To bootstrap annotations on an existing codebase, pyrefly infer writes annotations into source files using static analysis:

uv run pyrefly infer src/

See how to add type annotations with pyrefly infer for the full workflow.

Configuration Presets

Pyrefly groups error severities and behavior settings into named presets. The active preset is selected with preset = "..." in pyrefly.toml or [tool.pyrefly]. From the configuration docs:

  • off: silences every error kind. Useful for IDE-only users or projects that want to opt in to specific checks manually.
  • basic: low-noise, high-confidence diagnostics only (syntax errors, missing imports, unknown names). Applied automatically to projects without a Pyrefly config.
  • legacy: disables three Pyrefly check kinds mypy does not implement (bad-override-mutable-attribute, bad-override-param-name, unbound-name). Useful when migrating from mypy because the preset turns off the rule kinds most likely to produce a flood of mypy-absent diagnostics. Pyrefly’s other rules remain in place. pyrefly init emits this preset automatically when it detects an existing mypy configuration.
  • default: the standard Pyrefly experience. Equivalent to specifying no preset.
  • strict: enables strict-callable-subtyping, implicit-any, missing-override-decorator, and unused-ignore on top of default. Intended for codebases that want to keep Any out of their type surface.

Editor Integration

  • VS Code: install the Pyrefly extension from the VS Code Marketplace. The extension is the most-downloaded Python type checker on the Open VSX registry.
  • Neovim: supported through LSP configuration.
  • Zed: supported through built-in LSP integration.

For other editors, Pyrefly’s language server speaks LSP and can be used with any compatible client.

The Pyrefly 1.0.0 announcement describes upcoming compatibility with Pylance through the Type Server Protocol (TSP), which would let Pylance run Pyrefly as its analysis backend in any TSP-aware editor.

Complementary Tools

Pyrefly ships with two tools that support adoption in existing codebases:

  • pyrefly report: emits a JSON report with annotation-completeness and type-completeness metrics per function, class, and module, plus aggregate summary statistics. Useful for tracking how much of a codebase has reached full typing coverage over time.
  • Baseline files (experimental): snapshot the current set of errors to a JSON file (typically baseline.json) using pyrefly check --baseline=<path> --update-baseline. Subsequent runs report only errors not present in the baseline, as an alternative to inline suppression comments. Suppressed errors are still surfaced in the IDE.

Comparison to Other Tools

Pyrefly sits at a stable 1.0.0 release with over 90% typing-spec conformance, ahead of mypy and ty on the conformance suite and behind pyright and Zuban. It infers types more aggressively than ty, which follows a gradual guarantee that never adds errors to working code. Pyrefly and ty are competitive on raw speed; specific benchmarks shift release to release as both tools optimize. Tensor-shape checking for PyTorch ships as an experimental feature.

Learn More

Last updated on
pyproject.tomlpyright