Pyrefly — Fast Python Type Checker and Language Server by Meta

Introduction

Pyrefly is a Python type checker and language server developed by Meta. Written in Rust for performance, it analyzes Python code for type errors and provides IDE features like auto-completion, go-to-definition, and hover documentation through the Language Server Protocol.

What Pyrefly Does

• Type-checks Python code against PEP 484 type annotations at high speed
• Provides a language server with auto-complete, hover, and go-to-definition
• Supports incremental checking for fast feedback during development
• Handles large codebases with millions of lines efficiently
• Integrates with VS Code, Neovim, and other LSP-compatible editors

Architecture Overview

Pyrefly is implemented in Rust with a multi-phase pipeline: parsing (using a custom Python parser), name resolution, type inference, and error reporting. The language server runs as a persistent process that re-analyzes only changed files and their dependents. A query-based architecture ensures that repeated checks on unchanged code return instantly from cache.

Self-Hosting & Configuration

• Install via pip or download pre-built binaries for macOS, Linux, and Windows
• Configure via pyproject.toml or a dedicated pyrefly.toml config file
• Set strict or gradual typing modes depending on project maturity
• Exclude directories or suppress specific error codes via configuration
• VS Code extension available for one-click setup

Key Features

• Written in Rust for speed, checking large codebases in seconds
• Full Language Server Protocol support for rich IDE integration
• Incremental analysis re-checks only affected files on save
• Supports modern Python typing features including ParamSpec and TypeVarTuple
• Developed and battle-tested at Meta's scale

Comparison with Similar Tools

• mypy — the original Python type checker; Pyrefly is significantly faster due to its Rust implementation
• Pyright — Microsoft TypeScript-based checker; Pyrefly offers comparable speed with a different type inference approach
• Ruff — fast Python linter; Ruff handles style and lint rules while Pyrefly focuses on type correctness
• Pyre — Meta's earlier Python type checker; Pyrefly is the next generation with a rewritten core
• Pylance — VS Code extension by Microsoft; Pyrefly is open source and editor-agnostic via LSP

FAQ

Q: How does Pyrefly relate to Pyre? A: Pyrefly is Meta's next-generation type checker, rewritten from scratch in Rust to replace the OCaml-based Pyre with better performance and maintainability.

Q: Does it support gradual typing? A: Yes. You can adopt type annotations incrementally. Pyrefly analyzes annotated code and infers types for unannotated code where possible.

Q: Which Python versions are supported? A: Pyrefly supports Python 3.8 and later, including the latest typing features.

Q: Can I use it alongside mypy or Pyright? A: Yes. Pyrefly can run in parallel with other type checkers, though results may differ on edge cases.

Sources

• https://github.com/facebook/pyrefly
• https://pyrefly.org