Who pyrefly is for#
Team migrating from Mypy
Migrates a large Python project from Mypy by running `pyrefly init` to port configuration, then `pyrefly suppress` to silence legacy errors and enforce types on new code only.
Developer wanting fast editor feedback
Installs the Pyrefly VSCode extension to get sub-10ms type-check feedback in the editor instead of waiting for a full Mypy run.
Data science team with Pydantic pipelines
Adds Pyrefly to CI to catch type errors in a Pydantic-heavy data pipeline before they reach production.
Library author releasing to PyPI
Uses Pyrefly to verify type annotations are complete and correct before publishing a new release to PyPI.
Django developer
Gets autocomplete and type errors on model fields directly in their editor using Pyrefly's built-in Django support.
The problem it solves#
Python type checking with Mypy or Pyright becomes painfully slow on large codebases: a full check of a project like PyTorch can take minutes, breaking the development feedback loop. Language servers with separate type checker and IDE backends produce inconsistent results between the CLI and the editor. Teams adopting type checking incrementally get blocked by the difficulty of migrating existing untyped code without triggering thousands of new errors in code they are not currently working on.
How it solves it#
1.85M lines/second, 15x faster than Mypy
Checks 1.85 million lines of code per second, 15x faster than Mypy on projects like PyTorch
Sub-10ms IDE recheck on save
IDE rechecks typically complete in under 10ms after saving a file, keeping the feedback loop tight
Full language server for VSCode, Neovim, Zed
Full language server: code navigation, autocomplete, hover information, inlay hints, and semantic highlighting in VSCode, Neovim, Zed, and more
Incremental migration from Mypy/Pyright
`pyrefly init` migrates existing projects from Mypy or Pyright; `pyrefly suppress` silences pre-existing errors for incremental adoption
Built-in Pydantic and Django support
Built-in support for Pydantic and Django with framework-aware model validation and field-type autocomplete
Production-proven at Meta scale
Production-proven at Meta across Instagram (20 million lines) and adopted by PyTorch and JAX
Strengths and trade-offs#
Strengths
- One engine for CLI and language serverThe same type-checking engine powers both the CLI and the language server, so results are consistent between your editor and CI with no divergence
- Incremental adoption via suppressIncremental adoption path via `pyrefly suppress` means you can start typing one file at a time without drowning in legacy errors
- Meta-scale production validationProduction scale validation at Meta provides confidence it handles real-world Python patterns at a scale most type checkers have not been tested against
- Stable 1.0.0 release with MIT licenseStable 1.0.0 release with MIT license and monthly minor releases
Trade-offs
- -Monthly releases may add new type errorsMonthly minor versions may introduce new type errors on upgrade, requiring attention; Pyrefly does not follow strict semantic versioning
- -Third-party plugin ecosystem less mature than MypyPydantic and Django framework support is built in, but third-party framework plugins are less mature than the Mypy plugin ecosystem
- -Roadmap driven by Meta's internal needsPrimarily developed by Meta; the project roadmap is driven by Meta's internal needs, so community feature requests compete with internal priorities
pyrefly vs alternatives#
pyrefly is an MIT-licensed Python type checker and language server that competes with proprietary IDE typing experiences such as Pylance in VS Code and PyCharm inspections.
vs Pylance: Pylance gives VS Code users a polished proprietary language server with Python analysis settings built into the Microsoft Python workflow. pyrefly is the better fit when you want the same checker available in CI, the terminal, VS Code, Neovim, Zed, and other editors, with one command-line tool and one set of diagnostics.
vs PyCharm: PyCharm is stronger when a team wants a full commercial Python IDE with inspections, navigation, refactoring, debugger, and JetBrains support in one product. pyrefly is narrower: it focuses on fast type checking, IDE diagnostics, language-server features, and migration from mypy or pyright with the pyrefly init command.
vs mypy or Pyright workflows: pyrefly is most compelling for large Python codebases that need faster checks and consistent CLI plus editor behavior. Existing mypy or Pyright setups may still be safer when plugin compatibility, long-established behavior, or exact diagnostic stability matters more than speed.
Install and self-host#
pip install pyreflyWhat it's built on#
- Languages
- PythonRustTypeScript
- Frameworks
- React
- Tooling
- esbuild
FAQ#
How do I migrate from Mypy?
Run pyrefly init at your project root. It reads your mypy.ini or setup.cfg configuration and generates a Pyrefly config. Then run pyrefly suppress to add inline suppressions for existing errors so you start clean without touching legacy code.
Is the CLI type checker the same binary as the language server?
Yes. The language server and CLI share the same type-checking engine. You get consistent results whether you are running a check in CI or getting hover information in your editor.
Does Pyrefly support Python 2?
No. Pyrefly targets Python 3 and the modern type annotation syntax introduced in PEP 484 and subsequent PEPs. Python 2 is not supported.
Similar open-source tools#
repowise
Codebase intelligence: MCP tools for agents, health scores for teams.
dograh
Open source voice agent builder with telephony and BYOK AI support
whishper
Local speech-to-text transcription and subtitling with a web UI
ego-lite
AI agent browser with shared Chrome state, zero cost
r3
Minimalist Forth language for games and systems programming
t3code
Control your coding agents from one interface