Pyrefly: a Rust type checker and language server for Python, from Meta

What Pyrefly solves, and who it is aimed at

Python type checkers historically split into two camps: a fast checker without a full editor experience, or a language server whose analysis is tied to a single editor. Pyrefly is Meta's attempt to ship both from one engine. The README describes it as a type checker and language server, available as a command-line tool and as an extension for VSCode, Neovim, Zed and others, with the stated goal of consistent results across the CLI and your editor.

The audience is teams with existing, large Python codebases. The README states that Pyrefly is the default type checker for Instagram's 20-million-line Python codebase at Meta, and that PyTorch and JAX have adopted it. Those are the project's own claims about its users, not independent measurements. For a smaller project, the more relevant part is the migration path: pyrefly init, pyrefly suppress and pyrefly infer exist specifically so a codebase with years of untyped or partially typed code can be brought in gradually rather than all at once.

How the checker and the language server share one engine

The repository is a Rust workspace, and the crate list in Cargo.toml shows how the work is divided. pyrefly_types holds the type representation, pyrefly_config handles configuration, pyrefly_python covers Python-specific modelling, pyrefly_graph and pyrefly_util provide supporting infrastructure, and pyrefly_bundled carries bundled data. The pyrefly directory is the main crate, pyrefly_wasm is the WebAssembly build used by the in-browser sandbox, and crates/pyrefly_lsp_test exists for language server tests. There is also a crates/tsp_types entry, which is not explained in the README.

The consequence of a single workspace is that the CLI and the language server consume the same type-checking crates rather than reimplementing analysis. That is the mechanism behind the README's claim of consistent results between the CLI and the editor. The release profile in Cargo.toml enables link-time optimisation, sets codegen-units to 1 and strips debuginfo, which is the usual shape for a binary that is expected to run quickly on large inputs.

Framework support is described as built in rather than plugin-based: the README lists Pydantic, Django and pytest, with model validation, field types, fixture navigation and autocomplete working out of the box. The README does not document how those integrations are implemented, so how much of a framework's dynamic behaviour is actually modelled is not something the README answers.

Installing Pyrefly and running a first check

The README gives the command-line install as a single pip command. It does not state a minimum Python version, so check that yourself before rolling it out.

pip install pyrefly

After that, the README's adoption path starts with pyrefly init, which sets up the project for Pyrefly. For a first real use, run the checker over a single file rather than the whole tree, which is exactly the incremental approach the README recommends.

pyrefly init
pyrefly check path/to/file.py

What you should see is a list of type errors for that file, or a clean exit if there are none. The README does not show sample output, so treat the exact formatting as something you will confirm on your own machine.

For an existing codebase with a backlog of errors, the README documents pyrefly suppress for silencing existing errors and pyrefly infer for generating type annotations. A typical sequence is to init, suppress the current error set so the build is clean, then work through suppressed errors at your own pace.

pyrefly suppress
pyrefly infer

The README does not document what pyrefly suppress writes or where it stores the suppressions. If your team needs an auditable record of what was silenced, that is a gap to investigate in the documentation before adopting.

For editor use, the README points to the IDE installation page and to extensions for VSCode, Neovim and Zed, plus the pyrefly.org sandbox if you want to try the checker in a browser without installing anything.

Where Pyrefly is the wrong tool

The clearest limitation is stated by the project itself. The README says Pyrefly does not follow strict semantic versioning, that minor versions contain more significant changes than patch versions, and that any version may introduce new type errors and other breaking changes. A monthly minor release cadence is fast for a tool whose output gates CI. If your pipeline treats a new type error as a build failure, an upgrade can break the build without any change to your own code. The README's answer is pyrefly suppress, but that means re-running a suppression step on every upgrade, which is ongoing work rather than a one-time migration.

There is also a scope question. Pyrefly is a type checker and language server. The README does not describe lint rules, formatting or import sorting, and the related questions about whether it is a linter are answered by the README's own framing: it checks types. A repository that currently relies on Ruff or Flake8 for style enforcement will still need those tools.

Finally, the README does not document rollback behaviour, configuration file format, or a list of unsupported Python features. On a codebase that leans on heavy runtime metaprogramming, that silence is a reason to test on a branch before committing to the tool.

Pyrefly compared with Mypy and Pyright

Mypy and Pyright are the two checkers the README names directly. The README states that Pyrefly type checks projects like PyTorch 15x faster than Mypy and Pyright, and that it checks over 1.85 million lines of code per second, with IDE rechecks typically completing in under 10 milliseconds after saving a file. Those figures come from the project, not from independent measurement, and the README does not describe the benchmark methodology.

The difference in approach that the README does support is packaging. Pyrefly ships as one Rust workspace that produces both a CLI and a language server, with framework support bundled into the checker. That is a different arrangement from treating the editor integration as a separate layer over a checking library. Whether that arrangement produces better results on your code is an empirical question the README cannot answer for you.

The migration commands are the other practical difference. pyrefly init, pyrefly suppress and pyrefly infer are named in the README as the adoption path from Mypy or Pyright, and the README explicitly recommends starting with one file and expanding at your own pace.

Release cadence, licence and upgrade cost

The version policy is the main operational fact. New minor versions land monthly, with patch versions in between as needed for critical fixes. Combined with the statement that any version may introduce new type errors, this means the upgrade cost is not zero even when nothing in your code changes. Budget for a suppression pass alongside each minor bump, or pin the version and upgrade deliberately.

The current release line is 1.3.0-dev.3, published on 2026-08-28, following 1.3.0-dev.2 on 2026-08-18 and 1.3.0-dev.1 on 2026-08-07. The dev suffix on the latest releases is worth noting if you prefer to track tagged stable versions. The last push to the repository was on 2026-08-28.

The licence is MIT, declared both in the repository and in the workspace package metadata in Cargo.toml. MIT is permissive and imposes no copyleft obligation on your own code. That is a factual statement about the licence identifier, not legal advice; if your organisation has specific licence review requirements, run it through them.

Editorial conclusion

Pyrefly fits teams with large Python codebases that want a fast CLI check and an editor language server from the same engine, and it is a reasonable first type checker for projects already using Pydantic, Django or pytest. It is a poor fit if you need strict semantic versioning: the README states that any version may introduce new type errors and other breaking changes, so pin the version and re-run pyrefly suppress on upgrade. Before adopting, verify that pyrefly init and pyrefly suppress behave as you expect on your own repository, because the README documents the commands but not their output.

Frequently asked questions

Official sources

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