Python is one of the primary languages at Google, powering everything from machine learning research to developer infrastructure and data pipelines. Across hundreds of thousands of files in our monorepo, fast and reliable static type checking is essential for maintaining code safety and developer velocity.
Today, Pyrefly—an open source type checker developed by Meta—is the Python type checker at Google.
Replacing our previous type-checking infrastructure with Pyrefly provided significant speedups for engineers and agents alike, while substantially reducing build-system compute resources.
Moving away from Pytype
For more than a decade, Google relied on Pytype, an internally developed type checker that pioneered Python type checking and collaborated with the open source community to create typeshed.
However, as Python’s typing system evolved rapidly, Pytype faced fundamental challenges. Because it operated by analyzing compiled bytecode rather than source ASTs, keeping pace with modern typing PEPs became an increasing maintenance burden due to bytecode instability across Python releases. In addition, it struggled to deliver the fast turnaround times required for modern development loops.
As detailed in the Pytype update, we decided that Python 3.12 would be the final supported version for Pytype, leading us to evaluate and adopt modern open source alternatives.
Why Pyrefly?
Pyrefly incorporates years of collective lessons from earlier tools across the Python typing ecosystem. When evaluating candidates to succeed Pytype, Pyrefly quickly stood out across three key areas:
Performance
Written in Rust, Pyrefly is designed for high throughput and lazy, parallel evaluation. In our internal benchmarks across various Google projects, it proved to be an order of magnitude faster than Pytype, while scaling smoothly across large dependency graphs.
Typing spec conformance
Pyrefly achieves strong conformance—scoring roughly 97% on the official typing conformance test suite—and is actively maintained to track new Python versions and typing PEPs. This comprehensive language support makes Python version upgrades across our monorepo smoother.
In addition to supporting new syntax, Pyrefly provides strict type safety in areas where Pytype was historically permissive. A notable example is unsound unions: Pytype allowed passing a value of a union type (such as int | None or int | str) to a function expecting a specific type (such as int), as long as at least one type in the union was compatible. However, Pyrefly enforces sound union checking, catching these mismatches:
# foo.py
def process_id(x: int) -> None:
...
def get_id() -> int | None:
...
val = get_id()
# Accepted by Pytype, but rejected by Pyrefly:
process_id(val)Actionable error diagnostics
Pyrefly provides Rust-style compiler diagnostics, displaying the offending code snippet with inline annotations that point directly to the root cause of type mismatches, sometimes with suggested fixes. E.g., for the foo.py example above, Pyrefly produces:
ERROR Argument `int | None` is not assignable to parameter `x` with type `int` in function `process_id` [bad-argument-type] --> foo.py:8:12 | 8 | process_id(val) | ^^^ | The declared type does not allow `None`. Consider narrowing the value with an `is not None` check.
Performance and infrastructure impact
Switching to Pyrefly brought measurable improvements across Google's developer ecosystem and infrastructure:
- Up to 98% faster incremental rebuilds: In developer edit-and-rebuild workflows (with a warm daemon during active editing cycles), Pyrefly delivered up to a 98% latency reduction across various targets. On large machine learning targets, type-checking times dropped from minutes to seconds.
- >90% critical-path reduction in clean builds: In cold-cache benchmark suites across major libraries and models, Pyrefly consistently reduced the type-checking share of the build critical path by 90% to 99%, eliminating a long-standing bottleneck in our build pipelines.
- >80% compute hardware savings: Pyrefly reduced Google’s daily peak compute occupancy for Python type checking by more than 80%, saving thousands of machine cores every day.
To illustrate this impact on developer workflows, the chart below compares total edit-and-rebuild latency between Pytype and Pyrefly across targets of varying sizes.
Developer feedback
Beyond aggregate metrics, Pyrefly improved the day-to-day development loop, allowing engineers and AI coding agents to catch bugs faster.
Here is what engineers across Google have shared about their experience:
"I haven't waited for a Pytype action to complete since our project switched [to Pyrefly]. It is doubly awesome for agentic coding. Type checking is faster than running the tests now." — Peter Hawkins, JAX Tech Lead
"I really like that Pyrefly gives super clear errors that point out exactly what's wrong." — Yotam Doron, Gemini Large Scale Pretraining
“Investing in Python tooling pays huge dividends for research velocity: Pyrefly keeps our experimental iterations fast and catches subtle bugs early with clear, actionable errors.” — Tom Ward, GDM Science
Looking forward
Adopting Pyrefly highlights the value of uniting behind shared open source developer tooling. We are deeply grateful to the Pyrefly team for their rapid turnaround and responsiveness on upstream issues throughout our rollout. We look forward to continuing our collaboration and contributing to the Python open source community.
To learn more about Pyrefly or try it in your own projects, visit the Pyrefly website and the Pyrefly GitHub repository.
