Skip to content

Pyrefly: Python Type Checker by Meta

by Tim Hopper · Markdown
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 ships on a monthly cadence and runs 10-50x faster than mypy and pyright on large codebases. It scores higher than ty, mypy, and pyright on the dashboard’s partial-credit metric for its tested development build (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. Hatch runs Pyrefly by default for its hatch check types command.

Zuban scores higher on that partial-credit metric and remains an alternative where its specific advantages matter. Pyright scores lower on the same metric.

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: understands Pydantic models, same-file Django reverse relationships, SQLAlchemy update().values() calls, attributes registered on PyTorch modules, and attrs class transforms. See the attrs docs.
  • Tensor shape types (experimental): tracks PyTorch tensor dimensions through Int[N] and Tensor[[B, S]] 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, inline documentation, workspace-wide symbol search, and cross-file references and hierarchies. Change Signature updates a function and its call sites together. Quick fixes remove unused imports or insert assertions to narrow optional values.
  • Typing spec conformance: On 11 September 2026, the dashboard’s tested Pyrefly development build scores 140.5/145 (96.9%) with partial credit, ahead of mypy, ty, and pyright and behind Zuban among the listed builds. See the Python typing conformance dashboard for current numbers.
  • Auto-migration: pyrefly init converts supported mypy or pyright settings into Pyrefly configuration. When checking files without a governing Pyrefly configuration, Pyrefly can migrate existing checker settings in memory.
  • Targeted suppressions: # type: ignore[pyrefly:<code>] suppresses one Pyrefly diagnostic without hiding unrelated diagnostics on the same line.
  • Adoption tooling: pyrefly coverage report emits annotation-completeness metrics as JSON, pyrefly coverage check --fail-under enforces a coverage threshold as a CI gate, and baseline files (experimental) snapshot existing errors so only new ones are surfaced.
  • CI output: --output-format junit-xml writes diagnostics in the JUnit XML format that Jenkins, GitHub Actions, and GitLab CI parse for test reporting.

Pros

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

Cons

  • Lower partial-credit conformance score than Zuban for the builds on the official dashboard
  • 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.

Pyrefly publishes prebuilt wheels for macOS, Linux, and Windows, including musllinux wheels for Alpine and other musl-based containers.

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 when no Pyrefly config or migratable mypy/pyright config is found, or migration fails.
  • 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.
  • all: enables every check, the strictest available setting.

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.

Pyrefly also runs as a Pylance backend through the Type Server Protocol (TSP), in early preview in VS Code Insiders. The Pyrefly 1.0.0 announcement covers the TSP design.

Complementary Tools

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

  • pyrefly coverage report: emits a JSON report with annotation-completeness and type-completeness metrics per function, class, and module, plus aggregate summary statistics. Pipe output to jq .summary.strict_coverage to extract a single metric for dashboards or CI logging.
  • pyrefly coverage check: exits non-zero when coverage falls below the threshold passed to --fail-under. Use as a CI gate to enforce minimum coverage on every pull request.
  • 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. Baselines can match by concise description to reduce churn when code moves. Use --prune-baseline to remove stale entries and --error-stale-baseline to reject them in CI. Suppressed errors remain visible in the IDE. baseline-error-level sets their CLI severity; --min-severity controls whether they are displayed and cause a nonzero exit.

Comparison to Other Tools

Pyrefly is stable. The dashboard’s tested development build scores higher with partial credit than mypy, ty, and pyright on that metric and lower than Zuban. It infers types more aggressively than ty, which follows the gradual guarantee: making types less precise should not introduce additional static type errors. 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.

Last updated on