Pyrefly 1.0: A Type Checker Meets the Real Project

From alpha to stable

Meta introduced Pyrefly publicly in May 2025 as a type checker and language-server project derived from its experience with Pyre. One year later, the Pyrefly 1.0 release notes marked the project stable on May 12, 2026. The notes say it had become the default type checker for Instagram and was adopted by projects including PyTorch and JAX. Those are upstream claims, but they establish a stronger production story than a synthetic benchmark alone.

Stability does not mean every Python project will receive the same diagnostics as mypy, Pyright, or ty. Pyrefly performs aggressive inference even when code has few annotations. That can reveal real inconsistencies in lightly typed code, while also flagging patterns that a more gradual checker accepts. The practical question is therefore not whether one checker wins in the abstract, but whether its model helps a particular codebase.

Migration is an experiment, not a switch

Pyrefly's migration guide recommends an incremental route: generate configuration, run it alongside an existing checker, and use a baseline or targeted suppressions to isolate new findings from inherited work. This lets a team compare diagnostic categories before changing a required CI gate. A baseline is a migration instrument, not proof that existing errors are harmless; assign owners and reduce it over time.

An independent evaluation from Posit compared Pyrefly, ty, Basedpyright, and Zuban across editor features, correctness, performance, and ecosystem health. Posit chose Pyrefly for Positron's data-science IDE workload, citing its inference and language-server experience, but explicitly said it was not a runaway winner. Basedpyright was more mature, while ty had a different gradual philosophy and faster measurements in Posit's setup. That is a useful pattern for adoption: test representative repositories and interactive tasks, document what matters, and preserve an exit path.

Let uv fix the environment boundary

A checker can only reason about imports it resolves. If a developer's editor, a local command, and CI point at different interpreters or dependency sets, their results may disagree before the checker evaluates any interesting application logic. uv can make that boundary explicit by managing Python versions, locking dependencies, and synchronizing an environment from the lockfile. Its project documentation explains that exact synchronization also removes packages absent from the lockfile, so teams should review the first sync rather than treating it as a harmless install command.

For a trial, pin the checker in the project or CI tool environment, select the same supported Python version everywhere, and run Pyrefly through the same locked context. uv is a companion here, not a requirement: an existing reproducible environment manager can serve the same purpose. The important result is that a diagnostic can be reproduced by another developer and by CI.

FastAPI makes annotations operational

FastAPI is a revealing test case because type hints cross the boundary between editor assistance and runtime behavior. The framework uses annotations to parse requests, validate values, build OpenAPI schemas, and drive interactive documentation. Its response-model guide also shows how declared output types affect validation, documentation, and serialization.

Pyrefly can catch mismatched calls and inconsistent application types before execution, but it cannot prove that an HTTP client sends the expected payload, authentication rules hold, or a database transaction behaves correctly. Keep runtime and integration tests. During migration, compare generated OpenAPI output and send representative requests through the service; this catches changes at the framework boundary that static analysis is not designed to observe.

A practical rollout

Start with one service or library whose owners can judge the results. Record the current checker's output, run Pyrefly beside it, and classify the differences instead of immediately suppressing them. Generate configuration with the migration tooling, review every broad exclusion, and create a baseline only for findings that cannot be addressed in the trial.

Next, reproduce the environment in CI, pinning the interpreter and dependencies with uv or the team's existing lock workflow. For a FastAPI service, run both the static check and the API test suite, then compare its OpenAPI schema. Promote Pyrefly to a required check only after the team has defined ownership for new diagnostics and a schedule for shrinking the baseline. Stable software makes that evaluation reasonable; a measured rollout makes it trustworthy.