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 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 worth evaluating for large Python codebases where mypy or Pyright feel slow and where aggressive type inference that catches errors in unannotated code is desirable. Its conformance score (87.8% of the typing spec test suite as of March 2026) is higher than both mypy and ty, though lower than Pyright.

Pyrefly is in beta. Active development, missing features, and breaking changes between releases are expected. 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.
• 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: passes 87.8% of the official Python typing conformance test suite (122/139 test files), ahead of mypy (58.3%) and ty (53.2%), behind Pyright (97.8%).

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
• Cross-platform: macOS, Linux, and Windows (including ARM64)
• MIT licensed

Cons

• Beta status with active development and known issues
• Slower than ty on many real-world codebases (ty benchmarks 2-3x faster than Pyrefly), and ty’s editor feedback is roughly 500x faster for incremental checks
• No pyproject.toml integration for configuration (uses its own pyrefly.toml or pyrefly init)
• Smaller community and fewer resources compared to mypy and Pyright
• Does not infer parameter types, only variables and return types

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

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

uv add --dev pyrefly
uv run pyrefly check

Editor Integration

• VS Code: install the Pyrefly extension from the VS Code Marketplace.
• 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.

Comparison to Other Tools

Pyrefly occupies a distinct position among Python type checkers. It infers types more aggressively than ty (which follows a gradual guarantee that never adds errors to working code) but has lower conformance than Pyright (97.8% vs 87.8%). On raw speed, ty is generally faster on single-machine benchmarks, but Pyrefly handles certain large packages (NumPy, Pandas) faster due to different parallelization strategies.

Learn More

• How do mypy, pyright, and ty compare?
• How to gradually adopt type checking in an existing Python project
• Pyrefly Documentation
• Pyrefly GitHub Repository
• Introducing Pyrefly (Meta Engineering Blog)
• mypy reference
• pyright reference
• ty reference