Pyrefly: A Rust-based Python type checker that prioritizes speed and framework awareness

The problem Pyrefly solves

Python type checkers like Mypy and Pyright are widely used, but they can be slow on large codebases and often require extra configuration to understand popular frameworks. Pyrefly targets engineers who work on big Python projects, such as Instagram's 20-million-line codebase, where type checking speed directly affects developer productivity. It also targets teams that use Pydantic, Django, or pytest, because those frameworks come with built-in support, reducing the need to write custom stubs or plugins. The README states that Pyrefly is the default type checker for Instagram's codebase at Meta, which suggests it was designed to handle real-world scale and complexity, not just toy projects.

How Pyrefly works: architecture and data flow

Pyrefly is written in Rust, which is a key reason for its claimed speed. The README states that it checks over 1.85 million lines per second and type checks projects like PyTorch 15x faster than Mypy and Pyright. In the IDE, rechecks typically complete in under 10 milliseconds after saving a file. This speed comes from a compiled language and an architecture designed for incremental checks, as described in the repository's ARCHITECTURE.md file. The language server and CLI share the same core, so results are consistent across the editor and the command line. The data flow is straightforward: you run the CLI or the language server, it parses your Python files, applies type inference and checking rules, and reports errors. The built-in framework support means that Pydantic model fields, Django model fields, and pytest fixtures are understood without extra configuration, which is a significant departure from tools that treat these as generic Python classes.

Getting started: installation and migration commands

You can install Pyrefly with pip: `pip install pyrefly`. That gives you the command-line tool. For IDE integration, the README points to installation pages for VSCode, Neovim, Zed, and other editors. The key migration commands are `pyrefly init`, `pyrefly suppress`, and `pyrefly infer`. `pyrefly init` presumably sets up a configuration file for your project, though the README does not detail the exact syntax. `pyrefly suppress` silences existing errors, which is useful when upgrading to a new version that introduces new type errors. `pyrefly infer` generates type annotations, helping you add types to untyped code. The README suggests you can start with one file and expand at your own pace, which implies a per-file or per-directory configuration. The exact command-line options are not in the README, so you would need to consult the documentation at pyrefly.org for full details.

Limitations and failure modes

One clear limitation is the version policy. Pyrefly does not follow strict semantic versioning: any version may introduce new type errors and other breaking changes. That means upgrading from 1.2.0 to 1.3.0 could break your build, and you must rely on `pyrefly suppress` to silence new errors. This is a deliberate trade-off for speed of development, but it is a real risk for teams that need stability. Another limitation is that the framework support is built-in but not necessarily exhaustive. The README mentions Pydantic, Django, and pytest, but if you use a less common framework or a custom pattern, you may still need to write type stubs or use type: ignore comments. The tool is relatively new, with the first stable release at 1.0.0, so the ecosystem of community plugins and resources is smaller than that of Mypy, which has been around for years. Finally, the speed claims are based on the README, not on independent benchmarks, so you should verify them on your own codebase.

Alternatives: Mypy and Pyright

The main alternatives are Mypy and Pyright. Mypy is the oldest and most established Python type checker, written in Python, which makes it slower but easier to extend with plugins. Pyright is written in TypeScript and is known for its speed and excellent language server support, but it is not open source in the same way as Pyrefly, which is MIT licensed. The key difference in approach is that Pyrefly is written in Rust, which gives it a performance edge, and it has built-in framework support, whereas Mypy and Pyright typically require separate plugins or configuration for Pydantic and Django. For example, Mypy needs the pydantic.mypy plugin, and Pyright has built-in support for some frameworks but not all. Pyrefly's migration commands are designed to ease the switch from both tools, which suggests it aims to be a drop-in replacement. However, the version policy and the relative newness of the project mean that you should test it against your existing type checking setup before committing.

Maintenance and upgrade cost

Pyrefly releases new minor versions monthly and patch versions as needed for critical fixes. This is a fast cadence, which means you will see new features and fixes regularly, but it also means you need to budget time for frequent upgrades. The README explicitly warns that any version may introduce new type errors, so upgrading is not a simple `pip install --upgrade`. You will likely need to run `pyrefly suppress` after each upgrade to handle new errors. The license is MIT, which is permissive and allows commercial use, modification, and redistribution, with no copyleft obligations. This is a positive sign for adoption, as it reduces legal friction compared to GPL or other restrictive licenses. The project is actively maintained, with the last push on 2026-08-28 and recent development releases, so it is not abandoned. However, the monthly release cycle and the lack of strict semantic versioning mean that you should have a process for testing new versions in a staging environment before rolling them out to your team.

Who should adopt Pyrefly and what to verify first

Pyrefly is a strong candidate for teams that work on large Python codebases and are frustrated by slow type checking. It is also a good fit for projects that heavily use Pydantic, Django, or pytest, because the built-in support can save significant setup time. If you are migrating from Mypy or Pyright, the migration commands are a clear advantage. However, if you need strict semantic versioning or a tool with a long track record, Pyrefly may not be the right choice. Before adopting, verify the speed claims on your own codebase. The README's benchmark numbers are impressive, but they may not reflect your project's structure. Also, check the framework support for your specific use cases. For example, if you use Pydantic v2 with complex validators, test that Pyrefly understands them correctly. Finally, set aside time for the monthly upgrade cycle and plan to use `pyrefly suppress` to manage new errors. In short, Pyrefly is a fast, framework-aware type checker that is production-proven at Meta, but its version policy and relative newness require careful evaluation before you make it your default tool.

Editorial conclusion

Adopt Pyrefly if you need a type checker that keeps up with large codebases and understands Pydantic, Django, and pytest out of the box, especially if you are migrating from Mypy or Pyright and want to start incrementally with pyrefly init, suppress, and infer. Do not adopt it if you require strict semantic versioning, because Pyrefly explicitly allows breaking changes in any version, or if you need a tool with a longer track record outside Meta. Before adopting, verify that the built-in framework support matches your specific usage patterns, test the migration commands on a representative subset of your code, and confirm that the monthly release cadence fits your upgrade tolerance.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes