Why Pyrefly

develop
check

Static type checking helps to catch bugs earlier and contributes to the long-term maintainability and overall quality of Python codebases. This post explains why we chose Pyrefly as our static type checker over other alternatives.

Published

December 18, 2025

Modified

July 6, 2026

Note

We initially decided to use mypy, but Pyrefly has recently made an official stable release, which is why we now switched to using that instead.

Context and problem statement

We already use type hints extensively in all our Python codebases to document intent, improve readability, and support richer IDE feedback. However, without a mechanism to enforce these annotations, they remain just guidelines, which can easily drift out of sync with the actual behaviour of the code. The goal of static type checkers is to verify that there are no inconsistencies between declared types and actual usage by analysing the code without executing it. Static type checking can be integrated both in local development workflows and CI/CD pipelines, effectively preventing type errors from entering the codebase.

Given that there are multiple static type checkers available for Python, the question then is:

Which static type checking tool should we adopt to enforce our existing type hints consistently across development and CI?

Decision drivers

The static type checker should:

  • Enforce existing type hints.
  • Integrate well with IDEs (particularly VS Code). Additional features like inline feedback and autocompletion are a bonus.
  • Integrate with existing GitHub CI pipelines.
  • Handle both typed and untyped dependencies.
  • Run fast enough for frequent checks during local development.
  • Be actively maintained, widely adopted, and well documented.
  • Improve the maintainability of our Python projects.

Considered options

The most popular static type checkers available for Python are:

Mypy

mypy is the oldest and most widely used static type checker. It is written in Python and developed by the Python community.

Benefits

  • Closely aligned with Python’s standard typing specifications (PEP 484 and related PEPs).
  • Very popular, well established, and widely used.
  • Good documentation and lots of resources.
  • Integrates well with most IDEs and CI pipelines.
  • Configurable.

Drawbacks

  • Slower than some alternatives for large codebases.
  • Does not provide its own language server for IDEs, relying on editor plugins (e.g., VS Code extensions) instead.

Pyright

Pyright is a fast static type checker for Python developed by Microsoft. It powers VS Code’s Pylance extension and can also run as a standalone CLI tool.

Benefits

  • Popular and widely used.
  • Very fast, suitable for large codebases and frequent local checks.
  • Native integration with VS Code via the Pylance extension, providing inline feedback, autocompletion, and error highlighting.
  • Can run in CI pipelines.
  • Configurable.

Drawbacks

  • As Pylance bundles Pyright and type stubs locally, but in CI pipelines the Pyright CLI relies on the CI environment, their diagnostics may not always match exactly.

Pyrefly

Pyrefly is a static type checker developed by Facebook/Meta. It focuses on speed and incremental checking, ideal for large codebases.

Benefits

  • Designed for high performance and fast feedback, particularly on large codebases.
  • Can be integrated into CI pipelines.
  • Pyrefly aims to provide better IDE integration, richer type inference, and more responsive developer feedback compared to Pyre.
  • Extremely fast.
  • Is aggressive with type inference, which means more issues can be caught. This is good for smaller or newer codebases.

Drawbacks

  • Less widely adopted than mypy or Pyright.
  • Pyrefly is relatively new and still evolving, making long-term stability and tooling support harder to assess. In June 2026, they officially released a stable version, so it is still very new.
  • Pyrefly was designed to address problems specific to Meta’s products and internal infrastructure.
  • It’s aggressive type inference can be a drawback for larger codebases, as it would require more effort at resolving those issues.

Ty

ty is an extremely fast type checker for Python, written in Rust by the creators of uv and Ruff.

Benefits

  • Very fast, probably the fastest of all alternatives.
  • Most common IDEs are supported.
  • Can be integrated into CI pipelines.
  • Comes with a language server offering code navigation, autocompletion, auto-import, and more.
  • Supports advanced typing features in modern Python.
  • Configurable.
  • We already use Ruff and uv, so staying in the same ecosystem for type checking is an attractive prospect.

Drawbacks

  • The newest project of all options considered.
  • Currently (July 2026) has no stable release.
  • Is more permissive compared to it’s closest alternative, Pyrefly, which means it may not catch as many issues (can be good or bad, depending on the size of the project).

Decision outcome

We decided on Pyrefly as it recently made an official stable release, and compared to mypy, it is just so much faster. It has all the necessary features we need, and it’s strictness aligns more closely with our values compared to the (unstable) ty.

Consequences

  • Because it is still new, issues may still arise that could lead to breaking changes in the future. But with the recent stable release, we expect this to be less of a concern.

Resources used for this post