# Pyrefly: Python Type Checker by Meta


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](https://pyre-check.org) 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](https://pydevtools.com/handbook/reference/mypy.md) and [pyright](https://pydevtools.com/handbook/reference/pyright.md) on large codebases, scores higher than [ty](https://pydevtools.com/handbook/reference/ty.md) and [mypy](https://pydevtools.com/handbook/reference/mypy.md) on the typing-spec conformance suite (over 90% per the [1.0.0 release notes](https://github.com/facebook/pyrefly/releases/tag/1.0.0); see the [Python typing conformance dashboard](https://htmlpreview.github.io/?https://github.com/python/typing/blob/main/conformance/results/results.html) 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](https://pydevtools.com/handbook/reference/pyright.md) 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?](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare.md).

## 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](https://pydevtools.com/handbook/reference/ty.md)'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](https://pyrefly.org/en/docs/tensor-shapes-tutorial-basics/).
- 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](https://pydevtools.com/handbook/how-to/how-to-add-type-annotations-with-pyrefly-infer.md).
- 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](https://htmlpreview.github.io/?https://github.com/python/typing/blob/main/conformance/results/results.html) 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](https://pydevtools.com/handbook/reference/mypy.md) and [pyright](https://pydevtools.com/handbook/reference/pyright.md) by 10-50x on large codebases
- Higher typing spec conformance than mypy and [ty](https://pydevtools.com/handbook/reference/ty.md)
- 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](https://pydevtools.com/handbook/reference/pyright.md) and Zuban on the official typing conformance suite
- Tensor-shape checking for PyTorch is still experimental

## Installation and Usage

```bash
# 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](https://pyrefly.org/en/docs/configuration/)). `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](https://pydevtools.com/handbook/reference/uv.md) project:

```bash
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:

```bash
uv run pyrefly infer src/
```

See [how to add type annotations with pyrefly infer](https://pydevtools.com/handbook/how-to/how-to-add-type-annotations-with-pyrefly-infer.md) 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](https://pyrefly.org/en/docs/configuration/#preset):

- `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](https://marketplace.visualstudio.com/items?itemName=meta.pyrefly) from the VS Code Marketplace. The extension is the most-downloaded Python type checker on the [Open VSX registry](https://open-vsx.org).
- 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](https://pyrefly.org/blog/v1.0/) 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`](https://pyrefly.org/en/docs/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](https://pyrefly.org/en/docs/error-suppressions/#baseline-files-experimental) (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](https://pydevtools.com/handbook/reference/mypy.md) and [ty](https://pydevtools.com/handbook/reference/ty.md) on the conformance suite and behind [pyright](https://pydevtools.com/handbook/reference/pyright.md) 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

- [How to migrate from mypy to Pyrefly](https://pydevtools.com/handbook/how-to/how-to-migrate-from-mypy-to-pyrefly.md)
- [How do mypy, pyright, and ty compare?](https://pydevtools.com/handbook/explanation/how-do-mypy-pyright-and-ty-compare.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 add type annotations with pyrefly infer](https://pydevtools.com/handbook/how-to/how-to-add-type-annotations-with-pyrefly-infer.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)
- [Pyrefly Documentation](https://pyrefly.org/en/docs/)
- [Pyrefly GitHub Repository](https://github.com/facebook/pyrefly)
- [Introducing Pyrefly (launch blog post)](https://pyrefly.org/blog/introducing-pyrefly/)
- [Introducing Pyrefly (Meta Engineering Blog)](https://engineering.fb.com/2025/05/15/developer-tools/introducing-pyrefly-a-new-type-checker-and-ide-experience-for-python/)
- [mypy](https://pydevtools.com/handbook/reference/mypy.md) reference
- [pyright](https://pydevtools.com/handbook/reference/pyright.md) reference
- [ty](https://pydevtools.com/handbook/reference/ty.md) reference