Here are five real categories of bugs that Pyrefly catches, none of which are straightforward type mismatches.

1. The Silent Coroutine​

This code runs without error but silently fails to send a notification.

async def send_notification(user_id: int, message: str) -> None: ...

async def handle_request(user_id: int) -> None:
    send_notification(user_id, "Request received")  # bug!
    process_request(user_id)

(See the code in the sandbox.)

Spot the bug? send_notification is an async function, and calling it without await creates a coroutine object that is immediately discarded. The notification never sends. Python won't raise an exception — you'll just get a RuntimeWarning that's easy to miss in logs.

Pyrefly flags this as an unused-coroutine: the result of an async function call was neither awaited nor assigned to a variable. The fix is simple:

await send_notification(user_id, "Request received")

2. The Forgotten Call​

This code attempts to check whether a user is authorized before performing an action.

def is_authorized(user: User) -> bool:
    return user.role in ADMIN_ROLES

def handle_admin_request(user: User) -> Response:
    if is_authorized:  # bug!
        return perform_action()
    return Response(403)

(sandbox)

However, the action is always performed regardless of authorization. is_authorized (without parentheses) is a reference to the function object, which is always truthy. What was meant was is_authorized(user).

Pyrefly catches this as a redundant-condition: it knows that is_authorized is a function, and a function is always truthy, so the condition is redundant.

3. The Breaking Rename​

class BaseCache:
    def get(self, key: str, default: object = None) -> object:
        ...

class RedisCache(BaseCache):
    def get(self, key: str, fallback: object = None) -> object: ...  # bug!

(sandbox)

This looks harmless. RedisCache.get has the same types as BaseCache.get, just a different parameter name. But any caller using cache.get("x", default=None) will break when the cache is a RedisCache, because RedisCache.get doesn't have a parameter named default.

Pyrefly reports this as bad-override-param-name: a subclass renamed a parameter that callers might be passing by keyword. This is a violation of the Liskov Substitution Principle because you can't safely substitute a RedisCache where a BaseCache is expected.

It's easy to dismiss this as unlikely, but it happens a lot in practice. Someone inherits from a base class, doesn't look at the parameter names carefully, and chooses a name that makes more sense for their implementation. The bug only surfaces when someone passes the argument by name, which might be rare enough that tests don't cover it.

4. The Missing Case​

from enum import Enum

class Color(Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

def to_hex(color: Color):
    match color:
        case Color.RED:
            return "#ff0000"
        case Color.GREEN:
            return "#00ff00"
        # forgot BLUE!

(sandbox)

Pyrefly warns about this with non-exhaustive-match: the match statement doesn't cover all members of Color and has no wildcard default. If someone passes Color.BLUE, Python falls through the match without entering any case, and the function implicitly returns None, which may then cause a confusing error somewhere downstream.

5. The Misleading Comparison​

This code attempts to check whether a user is an admin.

class User: ...
class Admin(User): ...

def check(user: User) -> None:
    if user is Admin:  # bug!
        print("Welcome, admin!")

(sandbox)

This checks whether user is the same object as the Admin class, not whether user is an instance of Admin. What was almost certainly meant was isinstance(user, Admin). Pyrefly flags this as an unnecessary-comparison: using is to compare a value against a type is almost always a mistake.

Why a Type Checker?​

You might wonder: shouldn't a linter catch these, rather than a type checker? Without an understanding of the types flowing through your program, a linter can see that you wrote if f:, but it might not be able to tell that f is a function, especially if f is imported. Pyrefly's type analysis allows it to report diagnostics that non-type-aware linters cannot detect with confidence.

To see the full list of error kinds Pyrefly supports and their severity levels, check out our error kinds documentation. And if there's a bug pattern you wish we'd catch, let us know on GitHub or Discord.

Type checking sits right in the sweet spot for agents. It's fast enough for iterating small fixes, robust enough to catch issues of varying complexity, and actionable enough for an agent to make changes. In this post, we walk through how to integrate Pyrefly into your agentic workflow so that every piece of generated code can get type checked automatically.

TL;DR: We recommend:

• Adding a skill file for your agent with an agent.md directive to ensure the project checks clean before finishing a feature.
• If your model doesn't trigger this reliably, set up a hook on the Stop event.

1. CLI Skills​

If you've been working with agentic workflows, you've likely defined skill files before. These files instruct the agent how to perform a specific task or use a specific tool. For a type checker like Pyrefly, you might want a simple skill like this:

---
name: pyrefly-cli
description: Instructions to type check using Pyrefly's CLI. Use when function signatures of APIs change to validate program's types.
---
Run `pyrefly check` at the root of the project. Try fixing all possible type errors before running `pyrefly check` again.

These files are generally placed in the .agent/skills folder in a file called skill-name.md. See the full example here.

Agents generally use the title and description to understand when to use a skill. It's important for the description to state clearly when to use it, otherwise it might be invoked too often (wasting tokens) or not frequently enough.

We've noticed that a skill on its own does not always lead to a type check, even when the skill's description is clear it must be run. We tested Claude Opus 4.6 with this skill description and found that it still didn't typecheck:

MANDATORY type checker. You MUST run this before completing ANY task that modifies Python files. Never skip this step.

Although your mileage may vary with different checkers, if you use a skill, we recommend also adding a directive in AGENTS.md to check on at the end of every task/feature:

## Type Checking

Before completing any task that creates or modifies Python files, you MUST:
1. Run `pyrefly check` at the root of the project
2. If there are any type errors, fix ALL of them
3. Run `pyrefly check` again to confirm 0 errors

Code available here.

For more information specific to you, see the wiki for your preferred agent:

• Claude Code Skills Documentation
• Gemini CLI Skills
• OpenAI Codex Skills
• Kiro Hooks

2. CLI Hooks​

Hooks differ from subjective skills in that they require an agent action for every occurrence of the specified event. These events often relate to tool usage or other fundamental stages of agent lifecycles.

If you already have pre-commit hooks set up, these may look familiar. In fact, they might work already! When the agent commits to the version control system, it will get pushback if these signals are enabled there.

For those not using pre-commit hooks, or for the agent to type check without making a commit, we recommend setting up agentic hooks.

We tested Pyrefly in Claude Code: In this tool, we recommend adding the typecheck command to the Stop event so it runs when the agent completes each task. To do this in Claude, add the following to your .claude/settings.json:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "pyrefly check >&2 || exit 2",
        "timeout": 30
      }]
    }]
  }
}

Available in our examples repository here.

Since Pyrefly outputs to stdout, we must redirect it to stderr for Claude to understand it. We must also return exit code 2 always for Claude to understand it.

Alternatively, you can have a hook schedule an agent to investigate the type errors:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all Python files pass pyrefly type checking. Run `pyrefly check` and check the results. If there are any type errors, return ok: false with the errors. $ARGUMENTS",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Available in our examples repository here.

It requires some custom instructions, but we've found this approach to work well. Note the "agent" hook seems similar to the "prompt" hook, but you must use the "agent" hook for Claude to be able to use the Pyrefly tool.

For more information, or specific details for your agent, see the documentation on hooks:

• Claude Code Hooks
• Gemini CLI Hooks
• OpenAI Codex Hooks
• Kiro Hooks

Conclusion​

Developer tooling like Pyrefly is no longer only used by developers, it's useful for agents as well. Adding Pyrefly to your agentic workflow can be an easy way to improve the reliability of the code your agents produce.

Give these suggestions a try! Let us know which approach works best for you or if you have other solutions!

We frequently hear from developers who are excited about the new generation of checkers (Ty and Pyrefly) and want to know how they stack up against each other and the existing, established tools (Mypy and Pyright). In this comparison, we'll focus purely on performance (time to run a full check) and talk a little bit about how design choices, architecture, and features impact that latency.

Evaluating a type checker's performance presents a challenge due to many variables, including diverse evaluation metrics and varying results across different operating systems and hardware configurations. Furthermore, unlike the official test suite for typing specification conformance, there is no universally adopted benchmark for performance used by all type checker maintainers.

Nonetheless, in this blog post, we will attempt to compare speed and memory usage when checking several dozen packages from the command line. We use this performance data to catch regressions in Pyrefly changes that impact OSS packages — we previously only measured type checking performance on internal projects with Pyre1.

Before we start, we'd like to caution that these numbers are only a snapshot at the time of publication and will be out of date quickly. Performance numbers can swing wildly from release to release, because the type checkers are under active development.

Why Performance Matters​

Fast tooling is an essential part of an efficient developer flow. This is even more important in the age of agentic AI in our IDEs and CLI; they need diagnostics to generate high quality code. The faster, the better.

As codebases grow, the difference compounds. A package like numpy takes Pyright over a minute (70.9s) and over 3 GB of RAM to check on a MacBook M4. Pyrefly checks it in 4.8 seconds with 1 GB of RAM. When you multiply that across dozens of repos in CI, the gap matters.

The Benchmark​

We extended the Python Package Type Coverage Report to include a type checker performance dashboard that measures this systematically and shows trends as the new checkers ship regular improvements. Every day, we run the type checkers against the same 53 popular open-source Python packages on GitHub Actions (4 cores, 16 GB of RAM) and record execution time and peak memory usage.

The methodology is straightforward: clone the repo and install dependencies (best effort), run each checker with default settings (with the exception of Mypy, which is run in strict mode to match the other checkers), measure wall-clock time and memory. Each checker gets a 5-minute timeout per package.

The dashboard is useful for automation, trend analysis, and reflects the performance you should expect for your CI-based type checks.

For the sake of this blog and a more accurate reflection of day-to-day programming, we will share the benchmark from a local run on a MacBook M4 with 64 GB of RAM. In our local runs, we check each package 5x with a warmup run beforehand, but we do not cache results between runs (meaning that we don't use Mypy's warm check feature, and all checkers check the whole project from scratch each time).

The Results​

We tested Pyrefly 0.60.0, Ty 0.0.29, Pyright 1.1.408, and Mypy 1.19.1 across 53 popular open-source packages. Here's how the checkers compare head-to-head:

Small/medium packages (under 1s for the fastest checker — e.g., flask, requests, sentry-sdk): Pyrefly and Ty both complete in a fraction of a second, typically within 100ms of each other. Pyright and Mypy take 2-20x longer on these same packages.

Large packages (1-5s for the fastest checker — e.g., pandas, tensorflow, homeassistant): Pyrefly and Ty remain in the same ballpark, usually finishing within a few seconds of each other. Pyright and Mypy can take 10-50x longer — Pyright needs 144s for pandas, where Pyrefly takes 1.9s and Ty takes 1.5s.

Extra-large packages (scipy, numpy, sympy): These stress-test overload resolution and union handling. Both new checkers stay under 5s on most of them, though individual packages can be outliers — Ty takes 30.6s on numpy (likely a bug that will be fixed in a later release), while Pyrefly takes 4.8s; conversely, Ty checks sympy in 1.6s vs. Pyrefly's 4.0s. Pyright can take over two minutes on these packages.

At Meta's scale, Pyrefly checks Instagram's 20 million line codebase in ~30 seconds. The bottom line: both Pyrefly and Ty are an order of magnitude faster than Pyright and Mypy, and they use significantly less memory doing it. Pyrefly uses less memory than Ty on 31 of 53 packages tested, and the gap widens on larger projects.

The variance in performance between checkers can be explained by several reasons:

• Implementation language — Mypy is written in Python and Pyright is written in TypeScript, while the two newer checkers are written in Rust, which is a lower-level systems language.
• Architecture — Although Pyrefly and Ty are both written in Rust, their architectures are not the same. One of the reasons the Pyrefly team chose not to use Salsa (a Rust caching framework used by Ty) is to have more control over when memory is freed, which may explain the differences in memory usage.
• Inference — Features like return type inference (Pyrefly, Pyright) and empty container inference (Pyrefly, Mypy) all have a performance cost when checking un-annotated code. Doing less inference means faster results, but it also means a type checker may not catch as many bugs.
• Feature completeness — The set of supported features can impact both performance and memory usage.
• Maturity/Stability — By virtue of being less mature and not yet stable, the newer type checkers have more opportunities for optimization, but also have a higher chance of regressions between releases.

Why Some Packages Take Longer to Check​

Not all packages are equal from a type checker's perspective. Several factors drive the spread:

• Codebase size. Some projects like yt-dlp and transformers have a lot of code to analyze.
• Dependency graphs. Packages like airflow pull in many other packages as dependencies.
• Unions and overloads. These language features tend to be expensive to check, so many checkers put a cap on the maximum size of unions to keep performance more predictable.
• Type coverage. Not all packages have type annotations or stubs, and the ones that do may not be fully annotated. Packages with low type coverage tend to be slower to check, because inferring types for un-annotated code can be expensive.
• Configuration. Disabling certain features like return type inference will typically improve performance at the cost of more precise types. When return type inference is disabled, un-annotated functions will return Any.

The biggest spreads we see are on scientific computing packages. Pyright's performance suffers the most here: scipy takes 151 seconds, pandas 144 seconds, and sympy 80 seconds. These packages tend to be the most challenging to type check, containing methods with dozens of overloads and type aliases of large unions. These packages also tend to have un-annotated code, which compounds the problem because type checkers that infer return types (Pyright and Pyrefly) may produce large unions for un-annotated functions.

Pyrefly Design Choices​

There are two important performance questions that should be considered when building a type checker:

• How fast is fast enough?
• Do we prioritize speed over everything else, or are there features we want to include even at a performance cost?

For Pyrefly, "fast enough" means being able to check most projects in seconds, and smaller projects in a fraction of a second. We've largely achieved that goal, checking Instagram's 20 million line codebase in ~30 seconds.

Beyond that, we want to be efficient with memory to support local development workflows, and support advanced inference features to provide greater type safety to users. These priorities are reflected in our design choices:

• By having inference features be on-by-default, we aim to provide greater type safety out of the box. To mitigate the performance costs of that decision, we have guardrails like limiting the width of unions inferred for returns.

In the last few months, we've shipped improvements that have more than doubled Pyrefly's speed and significantly reduced its memory usage. We believe there is still significant room for improvement before Pyrefly reaches its theoretical performance ceiling, and we have a few more tricks up our sleeves to improve performance in coming months.

Try It Yourself​

The benchmark runs on GitHub Actions with standard runners. Your local machine, your codebase, and your configuration will produce different results. Install the new checkers in your project or clone the repository and give the benchmark a try:

# Clone the repo
git clone https://github.com/facebook/pyrefly.git
cd pyrefly/scripts/benchmark

# Create a venv and install type checkers
python -m venv .venv
source .venv/bin/activate
pip install pyright pyrefly ty mypy

# Run the typecheck benchmark on a few packages
python typecheck_benchmark.py --packages 5

# Run specific packages
python typecheck_benchmark.py --package-names requests flask django

# Or run it on all 53 tracked packages
python typecheck_benchmark.py

Picking the Right Type Checker for Your Project​

There are a number of factors to consider when choosing a type checker. The good news is that all of the new Rust-based type checkers are fast, guaranteeing performance for your codebase no matter which one you pick. We've done additional comparisons in previous posts to help look at other features that you might consider when choosing a checker: conformance to the typing specification, product choices around inference, narrowing, and IDE feature support. You can also review the criteria that Positron used when evaluating the Language Server Protocol (LSP) for their IDE, which includes factors like GitHub issue response time and community health, among others.

Whether you are new to type checking or have been here since day one of PEP-484, we hope you can get the benefits of types in your Python. If you try Pyrefly, we would love a ping in Discord or a new issue on GitHub with feedback.

Source code and methodology at https://github.com/facebook/pyrefly/blob/main/scripts/benchmark/README.md. Raw benchmark data for this post is available at scripts/benchmark/results/2026-04-08-benchmark-macbook-m4.json.

But notebooks have historically been second-class citizens when it comes to IDE features. Language servers, which implement the Language Server Protocol (LSP) to provide features like go-to-definition, hover, and diagnostics across editors, were designed with regular source files in mind. The language server protocol did not include notebook synchronization methods until five years after it was created, and the default Jupyter Notebook experience is missing many of the aforementioned IDE features.

In this post, we'll discuss how language servers have been adapted to work with notebooks, how the LSP spec evolved to support them natively, and how we implemented notebook support in Pyrefly.

How Language Servers Handled Notebooks Before LSP 3.17​

Prior to LSP 3.17 (released in 2022), the protocol only supported regular source files. Editors had to write custom adapters to make language servers work with notebooks at all.

The most common approach, used by both JupyterLab's LSP extension and Meta's internal Bento notebooks, is a proxy layer that intercepts and rewrites all language server requests and responses. The proxy concatenates every cell in the notebook into a single virtual document, and presents that view to the language server. Positions relative to a cell are mapped to positions in the concatenated file before being sent to the server, and positions in responses are mapped back to the corresponding cell before being returned to the editor. From the language server's perspective, it's just analyzing a regular file.

This approach worked, but it pushed all the complexity onto the editor or a middleware layer. Every editor that wanted notebook support had to independently implement cell-stitching and position-mapping logic, but it was language-agnostic and allowed language servers to be used with notebooks at a time when the LSP did not support it directly.

Notebook Support in LSP 3.17​

LSP 3.17 introduced four new operations for notebook documents: notebookDocument/didOpen, notebookDocument/didChange, notebookDocument/didSave, and notebookDocument/didClose.

The key difference from regular textDocument operations is how content is represented. Instead of sending a single file's worth of text, notebookDocument/didOpen sends the contents of each cell as a separate document, with a unique URI assigned to each cell by the editor. notebookDocument/didChange encodes information about added and deleted cells, along with content changes within individual cells.

By moving notebook awareness into the protocol itself, the spec lets language servers handle notebook semantics directly rather than relying on each editor to implement its own proxy layer.

Approaches to Implementation​

The LSP spec doesn't prescribe how a language server should represent notebooks internally. If you already have a language server that works on regular files, there are at least two ways to extend it for notebooks:

• File-based representation: Build the proxy logic directly into the language server. Concatenate all cell contents into a single virtual "file" and maintain a mapping between each cell and the corresponding lines. The core analysis stays the same, you just convert positions on the way in and on the way out.

• Cell-based representation: Treat each cell as a separate "file," with information about cell ordering. Each cell implicitly imports all symbols defined in previous cells. This allows each cell to be analyzed independently.

How We Did It in Pyrefly​

For the initial implementation in Pyrefly, we went with the file-based approach because the changes were less invasive. Everything works exactly the same as with regular files; we just map positions between cells and the concatenated source before and after each operation. This is similar to how jedi-language-server and Ruff handle notebooks.

That said, this isn't set in stone and we may revisit the decision in the future. The cell-based approach has some efficiency benefits: if a cell changes, you only need to re-check subsequent cells if the cell's exported types changed; preceding cells wouldn't need to be re-checked at all. With a file-based approach, the language server has to re-check the entire notebook whenever any cell changes. When a client requests diagnostics for a single cell, the server has to retrieve diagnostics for the whole notebook and filter the results to the requested cell.

In practice, this extra work hasn't been a problem for Pyrefly, especially if the data is cached. The average notebook is small compared to the scale Pyrefly is designed to handle.

What About Alternative Notebook Formats?​

The Jupyter .ipynb format (a JSON file containing cells, outputs, and metadata) isn't the only notebook format anymore. Projects like Quarto use markdown files with embedded code blocks, while Marimo stores notebooks as plain Python files where cells are individual functions. These formats are more version-control-friendly and integrate better with standard developer tooling.

Interestingly, these alternative formats face the same fundamental challenge when it comes to IDE features. Under the hood, their editor extensions still need to stitch cells together into a coherent view for the language server, much like the legacy proxy approach we described earlier. The architectural discussion in this post applies just as much to these formats as it does to traditional Jupyter notebooks; whether an editor or a language server handles the cell-to-file mapping, someone has to do it. Furthermore, Python is not the only language that is used in notebooks. Julia and R also benefit from interactive environments since they are used for many of the same tasks as Python. Other notebook environments support SQL, JavaScript, and more. If you have a working language server for a particular language and want to add notebook support, the approaches discussed here may be applied.

Try It Out​

We first shipped built-in notebook support for Pyrefly in v0.41.0, and it's available today in any editor that supports the language server protocol, including: VS Code, Positron, JupyterLab, and Marimo.

We'd love for you to try it out and let us know how it goes. If you run into any issues, please file a bug report: it helps us a lot, since real-world feedback is the fastest way for us to improve our notebook support.

At Pyrefly, we've always believed that type coverage is one of the most important indicators of code quality. Over the past year, we've worked closely with teams across large Python codebases here at Meta - improving performance, tightening soundness, and making type checking a seamless part of everyday development.

But one question kept coming up: What would it take to reach 100% type coverage?

Today, we're excited to share a breakthrough.

The Problem with "Almost Typed"​

Most teams plateau somewhere between 70–95% type coverage. The remaining gap is stubborn:

• Legacy modules with unclear ownership
• Dynamic code paths that resist annotation
• Utility functions that "just work" and nobody wants to touch

Traditional approaches - manual annotation, AI-assisted typing, gradual typing strategies - help, but they all share a common flaw: They assume all code is worth keeping.

A New Approach: Coverage-First Development​

We decided to reverse the problem. Instead of asking "How do we annotate the remaining code?", we asked:

"What if the remaining code simply didn't exist?"

Introducing Pyrefly Prune™, a new experimental mode that guarantees 100% type coverage by removing any code that isn't fully typed.

How It Works​

When you run:

pyrefly check --enforce-total-coverage

Pyrefly will:

• Identify any function, class, or module lacking complete type annotations
• Recursively analyze dependencies to ensure soundness
• Safely remove unannotated code paths
• Recompute coverage (now 100%)

The result is a codebase consisting entirely of fully typed, sound, and verifiable Python.

Early Results​

We piloted this approach on several large repositories.

Case Study: Web Serving Service​

• Before:
  • 82% type coverage
  • 1.2M lines of code
• After running Pyrefly Prune™:
  • 100% type coverage
  • 47 lines of code

The remaining code was described by one engineer as: "Incredibly well-typed. Also, it doesn't do anything anymore."

Case Study: Machine Learning Pipeline​

• Before: complex data ingestion, feature engineering, training loops
• After: a single, beautifully annotated function:

def model(x: float) -> float:
   return x

Training time improved dramatically.

Developer Experience Improvements​

Surprisingly, developers reported several benefits:

• Zero type errors (by construction)
• Blazing-fast CI (nothing left to check)
• Perfect IDE navigation (all remaining symbols are trivially understood)
• Reduced cognitive load ("There's just... less")

One team noted that onboarding time dropped from weeks to seconds.

Soundness, Perfected​

By eliminating all untyped code, Pyrefly Prune™ achieves a new level of soundness:

• No implicit Any
• No missing imports
• No edge cases

In fact, we believe this is the first system to achieve total program soundness by strategic absence. We call this approach Subtractive Soundness™.

Advanced Configuration​

For teams that want more control, we offer fine-grained pruning strategies:

[tool.pyrefly.prune]
aggressiveness = "maximal"
preserve_comments = false
preserve_readme = "optional"

# We also support selective retention:
keep_if_funny = true
keep_if_git_blame_is_yours = true

Roadmap​

We're actively working on several enhancements:

• Auto-replacement with TODOs Replace deleted code with thoughtfully written TODO comments that no one will ever complete
• LLM-assisted hallucinated implementations When code is deleted, generate a plausible replacement that type-checks but may not correspond to reality
• Executive dashboard metrics Track KPIs like:
  • Lines of code deleted per sprint
  • % of engineers quietly panicking
  • Revenue impact (TBD)

Frequently Asked Questions​

Q: Does this delete production code? A: Yes.

Q: Is there a rollback mechanism? A: We recommend strong git hygiene and emotional resilience.

Q: What about business logic? A: Fully typed business logic is preserved. Untyped business logic was, by definition, suspect.

Looking Ahead​

As AI agents increasingly generate and modify code, we believe the future belongs to systems that can maintain strong guarantees. Sometimes, the best way to ensure correctness... is to remove uncertainty entirely.

And if a small amount of functionality happens to be removed along the way - that's a trade-off we're finally ready to make.

Pyrefly Prune™ is available today behind the --enforce-total-coverage flag. Happy April Fools!

A lot of Pyrefly’s design comes directly from our experience with Pyre. Some things worked well at scale, while other things were harder to live with day-to-day. After running a type checker on massive Python codebases for a long time, we got a clearer sense of which trade-offs actually mattered to users.

This post is a write-up of a few lessons from Pyre that influenced how we approached Pyrefly.

The Origins of Pyre​

Pyre started around 2017, with roots in dataflow analysis tooling for Instagram. The Python tooling ecosystem looked pretty different back then:

• The typing specification didn't exist, and the type system was loosely "specified" through a series of PEPs describing individual features.
• Many modern typing features, such as literal types, dataclass transforms, param specs, type guards, etc. didn’t exist yet.
• The Language Server Protocol was new and not yet the clear standard.
• Mypy was, for all practical purposes, the only viable Python type checker available at the time.
• Type checking massive monorepos written in Python was still an unsolved problem.

These factors shaped the development of Pyre, but resulted in some limitations later on as the Python tooling ecosystem matured.

Language-server-first Architecture​

Pyre didn’t start out as a language server; it was designed as a static analysis tool you run in CI (continuous integration) or from the CLI (command line interface).

Consequently, its design prioritized throughput to minimize the total wait time for users by maximizing parallel CPU usage. Adapting this CLI tool to function as an editor-integrated language server presented a significant challenge, as an editor environment demands high priority on latency, not throughput.

Applying Pyre's throughput-focused strategy to an IDE degraded the user experience, often consuming excessive machine resources and potentially freezing the editor interface while performing computations the user might not currently need.

This struggle with Pyre's latency in the IDE led to a temporary move to Pyright as the language server for Meta developers. While this provided some features, it introduced other user experience issues, such as mismatched type errors and inconsistent IDE hover results.

A core design goal for Pyrefly is to create a system flexible enough to handle both throughput-oriented workloads (like CLI type checking) and latency-sensitive workloads (required by the IDE/language server).

Additionally, error-recovery during parsing is much more important for a language server than for a CLI-only type checker. Language servers need to continue working when you're halfway through an edit, while type checkers are typically run only when you're done with an edit. Pyre had several options for parsing, including a Menhir-based parser and directly calling the CPython parser, but these were not robust to syntax errors. In Pyrefly, we use Astral's excellent Ruff parser, which is both speedy and battle-tested.

OCaml vs. Rust: When Your Ecosystem Becomes a Ceiling​

Pyre is implemented in OCaml. To bootstrap quickly, we borrowed a multi-processing and shared-memory library from mature OCaml type checkers at Facebook, like Hack and Flow. This architecture was necessary because, prior to OCaml 5, the runtime relied on a global lock (much like Python's GIL) that prevented true multi-threading. Consequently, achieving parallelism meant relying entirely on OS-level process forking and inter-process communication (IPC).

While this borrowed architecture accelerated our initial development, it eventually forced us into a structural straitjacket:

• Data structure rigidity: Because of the IPC layer, shared data had to be crammed into string-to-string hashtables. Storing dynamic, complex objects (like self-referential types or closures) directly into shared memory incurred massive serialization and deserialization overhead.
• Algorithmic inflexibility: The IPC model is heavily biased toward throughput-oriented, strict "fork-join" workloads. This became increasingly awkward as we shifted toward latency-sensitive, demand-driven computational models that need to decide what to compute on the fly.

When OCaml 5 introduced native multi-threading, upgrading the compiler was tempting. However, we realized that language-level concurrency cannot erase historical platform baggage. OCaml's ecosystem has historically struggled with Windows, and as we deployed Pyre more and more broadly, we ran into platform related frictions more and more often.

Rust radically changes this equation by treating Windows, macOS, and Linux as true equals out of the box. Adopting an ecosystem where cross-platform reliability is a foundational tenet eliminated massive operational friction and completely unified our development experience when hacking on Pyrefly.

Switching to Rust also allowed us to grow our community of contributors much faster than if we had continued with OCaml.

Irreversible AST Lowering​

Early in the development of Pyre, a technique was used to accelerate iteration: leveraging the semantic similarity or equivalence between certain Python syntax patterns.

For instance, the following pairs are functionally similar:

Once code was implemented to handle one syntax pattern, support for similar or identical patterns could be rapidly added by using AST transformation passes to "lower" the latter into the former.

While useful, this technique introduced risks: If the original range and position information were not carefully preserved, the quality of diagnostics could suffer to the point where they could not adequately support language server features.

A significant example of taking this AST lowering too far in Pyre involved how variable scopes were handled. Pyre included an AST transformation pass designed to perform alpha-conversion: renaming syntactical definitions to resolve name conflicts.

Consider this original code:

from foo import x
def test():
  y = x
  x = "bar"
  z = x

The transformation process rewrote it as:

from foo import x
def test():
  y = foo.x
  _local_test_x = "bar"
  z = _local_test_x

This transformation successfully resolved the name conflict between the imported x from foo and the local variable x. However, a crucial piece of information was lost: the transformed code obscures the fact that the test() function never directly references the module foo. Losing this kind of detail can significantly impacted certain language server operations, such as refactoring and find-references.

Learning from Pyre, we made a conscious effort to minimize AST fabrication or transformation in Pyrefly’s design.

Attribute narrowing: Soundness vs. Usability​

Pyre was originally designed with a strong focus on security, leading to a high emphasis on the soundness of its type checking. Security engineers generally favor a low tolerance for false negatives (missed errors), even if it means a higher tolerance for false positives (incorrect warnings). Consequently, Pyre is quite strict and opinionated about Python code style.

A prime example of this strictness is how Pyre handles type narrowing for attribute access. Consider this code:

class C:
  x: int | str = ...

def narrowing_test(c: C) -> int:
  if isinstance(c.x, int):
    some_other_function(c)
    return c.x   # Pyre complains: `c.x` might be `str` here, incompatible with return type `int`
  ...

Technically, Pyre is correct. It cannot safely assume that some_other_function() won't mutate c.x to a different type, either directly or through an alias. To satisfy Pyre, users were forced to rewrite the code for safety:

def narrowing_test(c: C) -> int:
  c_x = c.x
  if isinstance(c_x, int):
    some_other_function(c)
    return c_x
  ...

This strictness significantly impacted ergonomics, and complaints about this specific behavior were among the most frequent feedback we received.

In Pyrefly, we made a deliberate choice to allow this kind of type narrowing, prioritizing a better user experience for more general Python audiences. This represents a conscious trade-off: in a gradually typed language, enforcing extreme soundness can make the tool feel overly brittle.

Caching Cyclic Data Dependencies​

Pyre was designed with a strict, sequential phased structure for its internal computations to ensure fast, incremental type checking. To maintain simple and cost-effective cache invalidation, Pyre enforced a rigid rule: computations could only rely on the cached outputs of preceding phases. This method generated a perfectly acyclical dependency graph, enabling the system to update its cache via a single topological sweep.

However, while this strictly unidirectional approach kept the cache invalidation logic simple, it was fundamentally at odds with how Python code is written in the real world.

The problem is that effective type checking Python naturally relies on recursive or "same-phase" dependencies. Consider a simple class hierarchy:

class A: ...
class B(A): ...
class C(B): ...

To compute the Method Resolution Order (MRO, the chain of class inheritance in Python) for C, it logically makes sense to just look up the already-computed MRO for B. However, Pyre couldn’t do this. Allowing C to depend on the cached result of B meant creating a dependency within the same phase. This violated the strict acyclic rule required by the caching system, meaning Pyre was unable to use its cache here. To get around this architectural wall, Pyre would have to recompute the MRO of B entirely from scratch, compute and cache C, and then throw B's intermediate data away.

While simple structural checks like MRO incurred an acceptable cost for this redundant work, the absence of intermediate caching created significant performance bottlenecks for more complex computations. This was particularly true for heavyweight tasks, such as inferring attribute types in the presence of descriptors and decorators (which itself necessitates inferring the types of other attributes used as such). Consequently, the type checker ran extremely slowly when encountering decorator-heavy code patterns.

This limitation drove the foundational design of Pyrefly. Instead of forcing the dependency graph to remain acyclic, Pyrefly’s engine was built from the ground up to embrace cycles. By incorporating cycle detection and fixpoint resolution directly into the underlying system, Pyrefly can safely untangle and cache recursive dependencies. This algorithmic shift absorbs the complexity at the infrastructure level, allowing the tool to run fast while empowering the type checker to use smarter, more flexible inference heuristics without artificial restrictions.

Conclusion​

Building a type checker is ultimately a deeply pragmatic exercise. It is easy to get lost in the weeds of type theory, but at the end of the day, we are building a tool that developers have to live with every single day. Pyre taught us how to scale to massive monorepos, but more importantly, it showed us exactly where the friction lies.

Pyrefly is the direct result of those hard-earned lessons. We looked at the paper cuts, the IDE latency, and the rigid rules that frustrated our users in Pyre, and we made fixing them our foundational requirements. We chose usability over absolute soundness, and we built an architecture that embraces Python's dynamism instead of fighting it.

But the most important lesson we applied to Pyrefly isn't about code; it’s about how we build. Pyre was born as an internal Meta tool that was later released to the outside world. With Pyrefly, we flipped the script. We’ve been building this in the open, from day one, specifically for the broader Python ecosystem. We want to build a tool that actually makes your day-to-day coding experience better, and we can't do that in a vacuum.

Come help us build Pyrefly! We’ve gratefully accepted hundreds of PRs from dozens of open-source contributors on Github so far, and we wouldn’t be where we are without them. Jump into our Discord, tell us what you are interested in, point out the rough edges, and help us figure out what lessons we need to learn next.

In this post, we look at what typing spec conformance means, how different type checkers compare, and what the conformance numbers don't tell you.

A brief history of the Typing Specification​

Python's type system started with PEP 484. At the time, the semantics of the type system were mostly defined by the reference implementation, mypy. In practice, whatever mypy implemented became the de-facto specification.

Over time, more type checkers appeared: Pyright (from Microsoft), Pytype (from Google), and Pyre (from Facebook), to name a few. Meanwhile, the type system itself continued to evolve through many different PEPs.

This created a problem: the semantics of the type system were scattered across many documents, and different type checkers implemented slightly different interpretations. To address this, the typing community began consolidating the rules into a single reference: the Python typing specification. The spec describes the semantics of typing features and includes a conformance test suite that type checkers can run to measure how closely they follow the spec.

The typing conformance test suite​

The typing specification includes a conformance test suite containing roughly a hundred test files. Each file encodes expectations about where a type checker should and shouldn't emit errors. The suite covers a wide range of typing features, from generics to overloads to type aliases. Within each test, lines are annotated to indicate where an error is expected. When a type checker runs on a file, two types of mismatches can occur:

• False positives: The type checker reports an error on a line that is not marked as an error in the test. This means the checker rejected code that the specification considers valid. For example, given this valid code:

  class Movie(TypedDict, extra_items=bool):
      name: str
  m: Movie = {"name": "Blade Runner", "novel_adaptation": True}  # OK
  

  If the type checker doesn't support extra_items, it will flag "novel_adaptation" as an unknown key, even though extra_items=bool explicitly allows extra boolean-valued keys.

• False negatives: The test expects an error, but the type checker does not report one. This means the checker failed to enforce a rule defined in the specification. Using the same Movie TypedDict from above:

  b: Movie = {"name": "Blade Runner", "year": 1984}  # E: 'int' is not assignable to 'bool'
  

  A false negative here means the type checker silently accepts "year": 1982 even though extra_items=bool requires extra values to be bool, not int.

The public conformance dashboard aggregates these results across type checkers and shows how many tests each tool passes. The table below summarizes the results as of early March 2026 (commit 62491d5c9cc1dd052c385882e72ed8666bb7fa41):

These results probably won’t be up-to-date for long (perhaps not even a week), given that Pyrefly, ty, and Zuban are all currently in beta and being actively developed. Readers in the future should refer to the latest results.

Pyrefly already supports all major type system features, and we expect to close the remaining gaps over the coming months.

Why conformance matters​

Does conformance matter in practice? After all, mypy (the reference implementation & industry standard for Python type checking) only fully passes 57% of test cases. Practically speaking, the less conformant a type checker is, the more you have to restructure your code to work around its limitations or inconsistencies. For example, you might follow a pattern recommended by the spec, read documentation that says a particular typing construct should work, and annotate your code accordingly, only to discover that your type checker doesn't correctly implement that part of the specification.

Even if you don’t use any advanced typing features in your own code, you may run into issues when you try to import something from a library that does use those features. When that happens, you may have to add a redundant cast, suppress a spurious error, or restructure your otherwise-working code to make the type checker happy, all because of a gap in conformance.

What conformance does not measure​

While conformance is a valuable benchmark to measure how feature-complete a type checker is, it’s not without limitations. For one, conformance mismatches are not equally meaningful - some tests check common patterns that appear in regular code, while others check for edge cases that are rarely seen in the wild.

Furthermore, even though the Python type system is becoming increasingly well-specified, many important aspects of type checking are not standardized at all, and therefore not covered by conformance tests. For example:

• Type Inference: The typing spec mostly focuses on the semantics of typed Python code. When annotations are missing, type checkers have much more freedom in how they infer types and how strictly they check un-annotated code. One common example where type checkers have divergent behavior is empty container inference.

• Type Refinement/Narrowing: The process of constraining a variable's type based on runtime checks is another area where behavior is only partially specified. The spec defines mechanisms like cast, match, TypeIs, and TypeGuard, but most real-world narrowing is implicit and relies on patterns that arise from dynamic Python code. These behaviors are implemented on a best-effort basis and support varies widely between tools. We explored several of these patterns in our post on type narrowing in Pyrefly.

• Experimental type system features: Intersection types, negation types, anonymous typed dictionaries, tensor shape types (more on this soon 👀)

Conclusion​

If you're trying to choose a type checker that's right for you, conformance is one useful metric: it tells you how closely a type checker follows the formal typing rules. But developer experience depends on many other factors, which you should also consider:

• Inference quality: How well does it infer types when annotations are missing?
• Performance: How fast is it on large codebases?
• IDE integration: Does it fully support the language server protocol?
• Error messages: Are errors clear and actionable, or cryptic?
• Third-party package support: Does it support packages like Django and Pydantic, which require special handling that can't be expressed in type annotations?

In future posts, we'll look at some of these dimensions and compare how different type checkers approach them. In the meantime, you can try Pyrefly yourself, or join the conversation on Discord and GitHub.

In order to improve the developer experience for pandas' users across the ecosystem, we at Quansight Labs (with support from the Pyrefly team at Meta) decided to focus on improving pandas' typing. Why? Because better type hints mean:

• More accurate and useful auto-completions from VSCode / PyCharm / NeoVIM / Positron / other IDEs.
• More robust pipelines, as some categories of bugs can be caught without even needing to execute your code.

By supporting the pandas community, pandas' public API is now type-complete (as measured by Pyright), up from 47% when we started the effort last year. We'll tell the story of how it happened - but first, we need to talk more about type completeness, and how we measure it.

But first - how is type-completeness measured?​

Pyright has a nifty little feature which helps us calculate the type-completeness of a library's public API. The general idea is:

• Find all public symbols exported by a package. For example, in pandas there's pandas.DataFrame, pandas.read_csv, pandas.Series, ...
• For each symbol, check where all its types are known. This includes function arguments, function return types, attributes, and base classes.
• If any type is unknown, then the whole symbol counts as unknown. For example, if a package exports a class Foo which has some missing type annotations, and a function def bar() -> Foo: ..., then the function bar also counts as type-unknown because it returns a type-unknown symbol (Foo).

Type-completeness is different from just calculating the percentage of missing type annotations, as it's biased towards heavily-used classes. In pandas, for example, Series appears as an argument and return type to at least some function in all of pandas' methods - therefore, no matter how type-complete the rest of pandas is, if Series isn't type-complete, then pandas' overall type-completess score will remain low.

By default, Pyright includes all public symbols. In practice, there are some pandas paths which are considered public according to Python's usual standards, but which pandas considers private, such as:

• pandas.tests.
• pandas.conftest.
• parts of pandas.core which aren't publictly re-exported in other places such as pandas.api.

We therefore amend Pyright's calculation to exclude these "technically public but not really" paths. This gave us a more useful measure of what part of the pandas API which users are expected to interact with is actually type-annotated.

Moving the needle in pandas​

Investigating sources of missing type-completeness in pandas was quite a circular exercise. For example, suppose that DataFrame and Series were type-complete, but Index had an untyped attribute. Here is what would happen:

• Index would be reported as "partially unknown" because of its untyped attribute.
• DataFrame would be reported as "partially unknown" because its method .index returns Index, which is partially unknown.
• Series is reported as "partially unknown" because its method to_frame returns DataFrame, which is partially unknown.

It was clear, therefore, that incremental progress would be difficult. Because of how intertwined pandas' classes all are, we expected the type-completeness score to flatline for several months before suddenly spiking. And that's exactly what happened! Progress flat-lined at around 60-70%, before spiking up to 100%.

How ruff helped​

pandas-stubs uses the ruff linter to enforce code quality standards. Ruff is highly configurable and comes with many optional ones, one of which is any-type (ANN401). A prerequisite to type-completeness is that types be present everywhere. In order to track progress, the ANN401 rule was enabled across the codebase, with a few exclusions which were then addressed gradually. The general rule was: if you make a pull request which types a certain part of the codebase, then remove the ANN401 exclusion for that part of the codebase so that it stays fully-typed in the future.

Ensuring that type-completeness stays this high​

Measuring type-completeness with Pyright is:

• Very easy if a package ships its own type annotations.
• Fairly tricky if a package relies on an external package for type annotations.

The situation for pandas is the latter, meaning that some extra work is needed to ensure type-completeness stays high in CI. In fact, it's even more complicated because there are parts of pandas which are technically public (according to Python's usual rules) but which pandas considers private! So, quite some work to get around Pyright's default score is needed.

The general idea is:

• Make a temporary virtual environment.
• Install pandas in it.
• Inline the pandas stubs into the same location, and add a py.typed file.
• Run pyright against the pandas package in that temporary virtual environment.
• Postprocess the output to remove technically-public-but-actually-private symbols.

The full script can be viewed in the pandas-stubs repo.

Beyond Pyright - what about "Pyrefly report"?​

Pyright's --verifytypes feature takes about 2 and a half minutes to run in pandas-stubs. There's room of improvement here - so much so, that the Pyrefly team is working on a pyrefly report which would work similarly. The pyrefly report API is not yet considered stable, so for now pandas-stubs uses Pyright's --verifytypes command, but hopefully a faster tool is on the horizon!

Conclusion and next steps​

I'm proud of how Quansight Labs (my employer), Meta, and open source communities were able to come together to make this happen. We plan to continue this work in other targeted open source projects, to keep supporting pandas and NumPy with the work we've already done, to improve typing support in IDEs such as Marimo, and to make pyrefly report production-ready.

Have any requests? Let us know on Discourse

Take this, for example:

def my_func(ys: dict[str, int]):
  x = {}
  for k, v in ys.items():
    if some_condition(k):
      x.setdefault("group0", []).append((k, v))
    else:
      x.setdefault("group1", []).append((k, v))
  return x

This seemingly innocent coding pattern poses an interesting challenge for Python type checkers. Normally, when a type checker sees x = y without a type hint, it can just look at y to figure out x's type. The problem is, when y is an empty container (like x = {} above), the checker knows it's a list or a dict, but has no clue what's going inside.

The big question is: How is the type checker supposed to analyze the rest of the function without knowing x's type?

Different type checkers implement distinct strategies to answer this question. This post will examine these different approaches, weighing their pros and cons, and which type checkers implement each approach. The information presented should be useful as you evaluate and select a type checker.

Strategy 1: Infer Any type for container elements​

The simplest approach is just to use Any type for the items in the container. E.g. if the developer writes x = [] then the type checker would infer the type of x to be list[Any]. This is what Pyre, Ty, and Pyright¹ mostly behave like at the time of writing.

Since the analysis does not require looking at any surrounding context at all, this approach is probably the easiest to understand and at the same time the most efficient for a type checker to implement.

Among the inference strategies we discuss today, inferring list[Any] produces the least amount of type errors: developers can insert anything into the list, and items read from the list will also be Any.

On the other hand, by inferring Any we are effectively giving up type safety. The type checker won't have any false-positive errors, but it also won't catch any bugs. In our experience using Pyre in Instagram, this lets expensive runtime crashes slip into production.

To illustrate the pitfalls, let’s look at code snippet simplified from a real-world example:

from dataclasses import dataclass

@dataclass
class MenuItem:
   title: str | None
   details: list[str]

def first_three_lines(menu_item: MenuItem) -> list[str]:
   lines = []  # `lines` is inferred as `list[Any]`
   if menu_item.title is not None:
       lines.append(menu_item.title)
   # bug: `list.append()` should be `list.extend()`
   lines.append(menu_item.details)
   return lines[:2]

This example has a bug where we accidentally call append instead of extend, creating a nested list instead of extending the list of strings. Using this strategy, the type checker infers the type of lines as list[Any] and does not warn the developer.

To improve type safety in these situations, type checkers that infer Any for empty containers can choose to generate extra type errors that warn the user about the insertion of an Any type. While this can reduce false negatives, it burdens developers by forcing them to explicitly annotate every empty container in order to silence the warnings.

Strategy 2: Infer the container type from all usages​

To infer a more precise type for an empty container, a type checker can look ahead and see how it is used.

def my_func(some_condition):
  x = []
  if some_condition:
    x.append(1)
  return x # `x` is inferred as `list[int]`

In this example, we see that after the initial definition of x, there’s a subsequent usage of x that attempts to append 1 to it. Based on that usage, it’s highly likely that the intended type for x would be list[int], and the type checker could infer that as the type for x.

But what happens if x has multiple uses later and each of them assumes different types? For example:

def my_func2(some_condition):
  x = []
  if some_condition:
    x.append(1)
  else:
    x.append("foo")
  return x # `x` is inferred as `list[int | str]`

One solution is to look at all usages of x, assume all of them are valid, and infer the element type of the container to be a union of them all. In our example above, the type checker would infer list[int | str]. This is the approach taken by the Pytype type checker.

This approach is very permissive for code that tries to insert into the containers: no type errors will be reported at insertion time at all, similar to the infer-Any strategies mentioned before. However, it provides better type safety over the infer-Any strategy when elements are read out of the container: any operations applied to the element must be valid for all inferred types in the union.

For instance:

def my_func3(some_condition):
  x = []
  if some_condition:
    x.append(1)
  else:
    x.append("foo")
  return x[0] + 1  # ERROR! `+` is not applicable to `int | str` and `int`

If we call my_func3(False), we will get a runtime crash that happens exactly where the type error is reported, so this inference strategy is also the one that models the Python runtime most closely.

However, the location of a runtime crash is not necessarily the same as the location of the bug that caused the crash.

While it’s helpful that the type checker gives an error when we try to use a value from a list that was modified incorrectly, what’s arguably more helpful is to know where we put the wrong thing into the list in the first place.

from dataclasses import dataclass

@dataclass
class MenuItem:
   title: str | None
   details: list[str]

def first_three_lines(menu_item: MenuItem) -> list[str]:
   lines = []
   if menu_item.title is not None:
       lines.append(menu_item.title)
   # bug: `list.append()` should be `list.extend()`
   lines.append(menu_item.details)
   return lines[:2] # error: `list[str | list[str]]` is not assignable to `list[str]`

In the example above, the error would be raised on the return statement (saying that list[str | list[str]] can’t be assigned to list[str]), even though the issue we actually need to fix is on the previous line. While this example is only off by a single line, in the real world the location of the error and the location of the bug could be separated by hundreds of lines of code.

Implementing this empty container inference strategy in a type checker faces several practical engineering hurdles.

• Firstly, finding all usages of a variable (especially those in non-local scopes like global variables or class attributes) can be computationally expensive, so a type checker may need to compromise on exhaustiveness to maintain good performance.
• Secondly, if a container has many distinct usages, the resulting inferred element type can be a lengthy and complex union, and this complexity can negatively impact the readability of subsequent error messages, necessitating the use of additional heuristics to improve error message quality.

Strategy 3: Infer the container type from only the first usage​

This is similar to strategy 2, but we infer the type based only on the first time the list is used, where “first” is defined in terms of syntactical appearance.

def my_func2(some_condition):
  x = []
  if some_condition:
    x.append(1) # `x` is inferred as `list[int]`
  else:
    x.append("foo") # error: cannot append `str` to `list[int]`
  return x

For example, in my_func2() above, the type checker infers the type for x based on its first usage x.append(1), which results in list[int]. When we do x.append("foo") on the following lines, the type checker emits an error saying we cannot insert str into list[int].

If x.append("foo") is actually intentional, we can overrule the type checker’s guess by annotating the empty container with list[int | str].

This is what Mypy currently does, and also the default behavior of Pyrefly.

The main benefit of this strategy is that the type errors it raises are closer to the location of the bug, so they are more actionable for finding and fixing bugs.

In our ongoing first_three_lines() example, Mypy and Pyrefly would both raise an error on the same line we need to change to fix the type error.

from dataclasses import dataclass

@dataclass
class MenuItem:
   title: str | None
   details: list[str]

def first_three_lines(menu_item: MenuItem) -> list[str]:
   lines = []
   if menu_item.title is not None:
       lines.append(menu_item.title)
   # bug: `list.append()` should be `list.extend()`
   lines.append(menu_item.details) # error: cannot append `list[str]` to `list[str]`
   return lines[:2]

Of course, this guessing strategy is merely a heuristic that assumes the first usage of the container signifies the programmer's intent.

When the type checker guesses wrong it can lead to false positive type errors. If the developer actually intended to create & return a list[str | list[str]], they can overrule the type checker’s inferred type by annotating the variable like lines: list[str | list[str]] = []. Unlike the first strategy which requires annotations on every empty container for safety, this approach provides type safety while only requiring annotations when you disagree with the type checker.

Summary​

The challenge of inferring types for empty containers in Python is more than a technical curiosity. It has real implications for code safety, developer productivity, and the effectiveness of type checkers. As we've seen, each strategy for handling empty container inference comes with its own trade-offs:

• Inferring Any (Pyright, Ty, Pyre) is the easiest approach that will throw the least amount of type errors, but sacrifices type safety.
• Inferring from all usages (Pytype) closely mirrors Python's runtime behavior, but it can complicate the process of identifying the root cause of bugs, particularly when the resulting errors manifest long after the initial mistake.
• Inferring from the first usage (Mypy, Pyrefly) provides more actionable error messages, helping developers fix issues at their origin, but may result in false positives if the initial usage doesn't reflect the programmer's true intent.

Ultimately, the choice of strategy depends on the priorities of your project and team, whether you value permissiveness, runtime fidelity, or actionable feedback.

The Pyrefly team believes that type safety is not the only goal of building a type checker – type errors also need to be actionable and easily-understood by users. As a result, we adopt the first-use inference by default which we believe gives the best balance of actionable error messages and type safety. We also recognize the need for greater flexibility from some users, so we've provided the ability to disable first-use inference, which would make Pyrefly behave more like Pyright.

What’s your take on empty container inference? Share your thoughts or questions with us on Discord or in a GitHub Discussion!

What are Python stubs?​

Stubs are Python files that provide type information about Python code. They can be found in files with the extension .pyi and define the signature of any functions, classes, etc, that are defined in the associated source file. Stubs can be very helpful for third party libraries or parts of the Python standard library that were not originally typed and allow us to use that type information to write safer code.

Why is stub information important?​

Being able to access this type information through stubs is very important during type checking. This is because it allows the type checker to verify that functions are being called with the correct argument types and that return values are being used appropriately, catching potential bugs before runtime. The inclusion of stubs also brings a lot of value to the IDE experience. The inclusion of these stubs greatly enhances certain code navigation functionality in the IDE when using these packages, as highlighted in the following examples

Pyrefly will now provide autocomplete suggestions for types in third party libraries.

Pyrefly will now also provide inlay hints for third party libraries with included stubs.

Hovering on types from packages with stubs will also now show the associated type rather than 'Unknown'.

before:

after:

How do I ensure this is part of my IDE experience?​

If you are just using Pyrefly out of the box with no custom configuration then no action is needed! Just ensure that you are on the latest version of Pyrefly. These stubs will be bundled along with the Pyrefly installation and become active in your IDE experience.

If you are using Pyrefly with a configuration through pyrefly.toml or pyproject.toml file, we will instead prompt you to install stubs for the specified package. Due to potential version mismatches between installed packages and bundled stubs, we prefer to use stubs directly installed by the user.

What Stubs are included?​

Currently all stubs found in the Typeshed repository are included.

The following stubs are also included starting with Pyrefly version 0.46

• Boto3
• Botocore
• Conans
• Matplotlib
• Pandas
• Scikit-image
• Scikit-learn
• Sympy
• Vispy

Further Work​

We have intentionally built out this support in such a way in order to very easily enable adding more stubs in the future. We invite you to share your feedback in discord, or by opening a GitHub issue. We’d love to know how these enhancements are improving your workflow or any issues you come across. Your input will help us shape future releases and ensure Pyrefly remains a robust tool for the Python community.

As we move closer to a stable release of Pyrefly, our efforts have moved from expanding the language server’s capabilities to tackling performance edge cases. Recently, our friends at Astral alerted us to a specific edge case that is a great example of the kind of issues we’ve been aiming to uncover. The specific example Astral highlighted showed that in some edge cases Pyrefly could take multiple seconds to update diagnostics after editing. This is much slower than expected (used across Meta’s codebases, Pyrefly usually takes less than 10 milliseconds to recheck files after saving them) and prompted us to investigate further.

Now we’d like to share the story of how that edge case led us to rethink our underlying approach to diagnostics and dependency tracking, improving the speed at which Pyrefly's type errors update by 18x in the process.

The Problem​

Say you’re working in a very large codebase and have two files open in your editor, A and B.

• A is a “load-bearing” file that has many reverse dependencies - that is to say, many files directly or transitively import A.
• B is one of the files that imports A.

Incremental type checking should be snappy - when you edit A and save the file, any effects on the type errors in B should be reflected almost instantly. However, in a small number of cases, we found that updates could take multiple seconds.

How Incremental Updates Work in Pyrefly​

To understand how this problem arises, we need to look at how incremental updates currently work. Pyrefly’s analysis operates at the module level, meaning it keeps track of the types exported from each module, as well as the dependencies between modules. Let’s illustrate with a simple example.

The above image demonstrates a file A that has 4 reverse-dependencies. B1-B4 all rely on the types exported from A.

When file A is edited & saved, we recheck A to see if any of its exported types also change. If so, we recheck every file that imports A (and if any of those files’ exports changed, we recheck their dependencies, and so on until the change to A has been successfully propagated everywhere). After all of that finishes, we display updated errors in the IDE.

There are two key observations here:

1. Our dependency tracking rechecks a module when any export changes, even if the module does not depend on the export that changed. This can lead to modules being rechecked unnecessarily.
2. We are waiting until the update has completely propagated to every affected file before sending any updated diagnostics, when in practice we mostly care about the files the user has open.

Solution 1: Fine-grained dependency tracking​

Instead of just tracking whether or not a module depends on another module for invalidation, we can specifically track what’s used.

Looking again at the example above, instead of rechecking everything that imports A, with smarter dependency tracking we could only recheck a subset of relevant files:

But the types a module depends on are not only from imports. Imagine a program like this with a chained method call:

from module import Class
Class().returns_type().operation_on_type()

Even though we only import Class, this module still depends on the type returned in returns_type().

Similarly, returns_type() could be implemented in a base of Class, so we really might be depending on a class hierarchy instead of just Class from module.

And should a change to an unrelated part of numpy invalidate this program (i.e. recheck the module)? Probably not.

import numpy as np
array = np.ones(1)

As you can see, a program’s type dependency structure is much more complicated and expansive than it might originally appear.

Since Pyrefly v0.51.1, we no longer invalidate a module any time a dependency changes. We now track exactly which types the module depends on at lookup to prune the modules that must be recomputed. In load-bearing files like the example in the introduction, this change turns what could be a 2000+ module invalidation into an invalidation of just over 100 modules.

Solution 2: Streaming diagnostics​

The other key insight from earlier is that we’re waiting for the update to finish completely before refreshing the errors in the IDE. To improve this, we could stream updated diagnostics to the IDE as soon as an open file has been rechecked, without waiting for other modules to be rechecked.

Let’s imagine a project with a dependency structure that looks like this. A is the file that we are editing, and B is another file that we have open, which is affected by edits to the types in A. As a user, what we want is for changes we make in A to be reflected in B with minimal delay.

Highlighted in red are the reverse dependencies of A, which may need to be rechecked if A is updated. Previously, we would recheck all the red modules before updating the diagnostics for B.

Highlighted in blue are the transitive dependencies of B. Only changes to those modules affect the types and diagnostics for B.

The image below shows the intersection of A’s reverse dependencies and B’s dependencies in purple. Once those modules are checked, we can show updated diagnostics for open files to the user, while continuing to check the remaining modules (red) in the background.

In order to provide a smooth IDE experience, Pyrefly runs language server operations (e.g. hover, autocomplete, go-to-def) on one thread and rechecks on another thread, that way users can still use language server features while a recheck is happening in the background. Previously, the main language server thread would send updated diagnostics to the IDE, and only did so once it received a signal from the recheck thread that a recheck had finished. Now with streaming diagnostics in Pyrefly v0.52.0, the recheck thread can emit the diagnostics to the frontend directly.

This change means that diagnostics can now be emitted from both the main thread and the recheck thread. To prevent conflicts between diagnostics sent from different threads, we add a restriction so that only one thread may send diagnostics for a given file at a given time. When a recheck is ongoing, the main thread cannot send diagnostics for any files eligible for streaming diagnostics.

Results​

Combined, these two optimizations enable Pyrefly to provide updated diagnostics 18x faster than before. Going back to the example from the introduction, these changes reduce the diagnostic update time from ~3.6 seconds to under 200ms on an M4 Macbook Pro. For users, this means type errors refresh instantly after saving a file, a dramatic improvement:

To see how we benchmarked this, you can check out testing instructions on GitHub here

What’s Next?​

This was a tricky case to fix and we’ve made significant progress, but how fast is fast enough?

Speed continues to be a top priority for us on the Pyrefly team. While we’ve addressed the core problem, we’re always on the lookout for opportunities to further optimize performance, so stay tuned for further updates and make sure to regularly update your Pyrefly version. As we move toward v1, we’re carefully weighing additional speed improvements alongside other critical priorities like memory efficiency, bug fixes, and enhanced inference capabilities. Our goal is to deliver the fastest experience possible without compromising on overall functionality.

As always, if you’ve found a problem, please let us know by opening a GitHub issue.

And if you’ve made it this far, thanks for journeying down this rabbit hole with us! We hope you give Pyrefly a try if you haven’t already, see you for the next update!

If we view a type of an expression or variable as the set of possible values it can resolve to, narrowing is the process of applying constraints on those values. For example, if you have a variable x whose contents you don’t know, an if isinstance(x, int) check will narrow the type of x to int inside the body of the if-statement.

Since Python is a duck-typed language, programs often narrow types by checking a structural property of something rather than just its class name. For a type checker, understanding a wide variety of narrowing patterns is essential for making it as easy as possible for users to type check their code and reduce the amount of changes made purely to “satisfy the type checker”.

In this blog post, we’ll go over some cool forms of narrowing that Pyrefly supports, which allows it to understand common code patterns in Python.

hasattr and getattr​

In a dynamic codebase where not every field is initialized in the constructor, you may encounter code that dynamically adds attributes to classes without declaring them in the class body.

Even if a field is not declared on the class, Pyrefly can understand a hasattr check indicates that the field exists.

def func(x: object) -> None:

   if hasattr(x, "value"):
       val = x.value # Pyrefly knows that `x` has the `value` attribute and won’t error here

Some fields are declared on the class but not always initialized, so accesses have to be done with getattr. To support this pattern, any checks on getattr(x, “field”) will generally narrow the type the same way as the same check on x.field. This means that using getattr() in a guard will narrow the field to be truthy.

from typing import Literal, assert_type

class C:
    flag: bool  # the flag is not always set`

def func(x: C) -> None:

   if getattr(x, "flag"):
       # here Pyrefly knows that the flag is set to True
       assert_type(x.flag, Literal[True])

Tagged Unions​

Tagged unions are a common feature in functional programming languages, but they are not a first-class language construct in Python. Although Python’s union types are untagged, Pyrefly can emulate a tagged union by creating a union where each member explicitly defines the same field to use as a tag. Pyrefly can then check the value of the field to narrow the union to the corresponding member.

This works for regular classes, as well as typed dicts.

from typing import TypedDict, Literal

class Ok(TypedDict):
   result: Literal["ok"]
   payload: bytes

class Err(TypedDict):
   result: Literal["error"]
   message: str

type Response = Ok | Err

def read(res: Response) -> bytes:
   if res["result"] == "ok":
        return res["payload"]
   else:
       raise Exception(res["message"])

Tuple length narrowing​

When you check the length of something against a literal integer, Pyrefly will narrow away any tuple types that definitely do not match that length:

from typing import assert_type

type XY = tuple[float, float]   # 2D point
type RGB = tuple[int, int, int]  # color

type Vec = XY | RGB

def describe(v: Vec) -> None:
   if len(v) == 2:
       x, y = v # Pyrefly knows v only has 2 elements, so it cannot be RGB
   else:
       r, g, b = v # Pyrefly knows v has 3 elements, so it cannot be XY

Conditions saved in variables​

If you want to check some condition multiple times, you may want to save it to a local variable to avoid repeating yourself. Pyrefly understands this pattern, while also being smart enough to figure out when it should invalidate a saved condition:

def f(x: int | str, y: int, z: int | str):

    x_is_int = isinstance(x, int)

    if x_is_int:
        y += x # here Pyrefly knows x is an int and won't throw an error

    if x_is_int:
        y += x # x has not changed, so pyrefly still knows that x is an int

    x = z

    if x_is_int:
        y += x # this is now unsafe, the x_is_int condition is invalidated so pyrefly will throw an error here

Conclusion​

These are just a few of the ways Pyrefly automatically narrows types, reducing the need for explicit casts in your programs. Not all of these features are unique to Pyrefly, but no other type checker as of writing supports the full set of narrowing patterns listed here. Given the lack of standardization of this feature, there’s a lot of room for innovation in the space. We’re currently working on expanding the narrowing patterns we support - so stay tuned for more updates!

Do you have a pattern for narrowing types that you wish type checkers could understand, or that you want us to support in Pyrefly? Please file an issue on our Github!

We’re excited to share that experimental support for Pydantic is now available in Pyrefly! This integration aims to provide a seamless, out-of-the-box experience, allowing you to statically validate your Pydantic code as you type, rather than solely at runtime. No plugins or manual configuration required!

Supporting third-party packages like Pydantic in a language server or type checker is a non-trivial challenge. Unlike the Python standard library, third-party packages may introduce their own conventions, dynamic behaviors, and runtime logic that can be difficult to analyze statically. Many type checkers either require plugins (like Mypy’s Pydantic plugin) or offer only limited support for these types of projects. At the time of writing, Mypy is currently the only other major typechecker that provides robust support for Pydantic.

Read on to learn more about how this works and how to get started, or watch the video!

Background - Pydantic Basics​

Pydantic leverages type annotations for data validation and parsing. Similar to Python’s built-in dataclasses, it helps you create structured data containers in your code. But Pydantic takes it a step further by providing extensive runtime data validation, ensuring that data matches the expected types and formats as soon as it’s instantiated.

For example:

from pydantic import BaseModel, Field

class User(BaseModel):
    id: int
    name: str = Field(..., min_length=1)
    email: str

# Example usage
user = User(id=123, name="Alice", email="alice@example.com")
print(user)

Using the code above, if you were to create a User instance, Pydantic would automatically validate the types and constraints. So if you pass invalid data (e.g., name="" or id="not an int"), Pydantic will raise a ValidationError at runtime.

Pyrefly & Pydantic - How it works​

So how does Pyrefly work with Pydantic? For this initial experimental support we focused on delivering the following experiences:

• Understands models and constructs: Pyrefly supports core Pydantic features, including BaseModel, Field, ConfigDict, as well as model-level configuration. No import errors or pesky red squiggles because your typechecker/language server doesn’t understand what Pydantic is.
• Automatic Recognition: Pyrefly detects Pydantic models and constructs out-of-the-box. There’s no need to install plugins, add configuration files, or tweak settings. You can just write your Pydantic code and Pyrefly will handle the rest.
• Static Analysis That Reflects Runtime Logic: One of the biggest challenges with Pydantic is that much of its validation and type coercion happens at runtime. Pyrefly’s static analysis engine is built to reflect Pydantic’s runtime logic as much as possible, ensuring that what you get in your IDE matches what will happen when your code runs.
• Immediate Feedback: As you write and edit your models, Pyrefly provides instant type errors and warnings. This helps you catch mistakes early, reducing debugging time and improving code quality.

For the full list of supported Pydantic features check out the documentation here.

Automatic Recognition - Write Pydantic-ally while Pyrefly gets out the way​

Let's take a closer look at how Pyrefly works differently to other type checkers, particularly in its unobtrusive approach. A key illustration of this difference is Pyrefly's interpretation of strictness.

Pydantic offers flexible validation modes to suit different use cases:

• Lax (Default) Mode: In this mode, Pydantic will automatically coerce types where possible. For example, if you pass ”123”(a string) to a field expecting an int, Pydantic will convert (i.e. coerce) it to 123 (an int). This is convenient for handling loosely-typed input, such as data from APIs or user forms.
• Strict Mode: here Pydantic enforces exact types, no coercion is performed. If you pass a string to an integer field, you’ll get a validation error. This is ideal for scenarios where data integrity is paramount.

The handy thing about Pyrefly is that it automatically respects your choices on this matter. It reads your model’s configuration (such as ConfigDict or model-level config) to determine which mode to apply. For example, in the following code we are explicitly setting the age field using strict mode. Pyrefly inspects this statement directly and adapts its analysis to match your intent (in this case by reporting an error if a string age is passed).

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str
    age: int = Field(strict=True) # strict mode

# Pyrefly will report an error here.
y = User(name="Alice", age="30")

Another useful example of this can be seen with the use of extra parameters. Sometimes when writing Pydantic models you want to allow extra unspecified parameters when creating a model, and other times you want to explicitly forbid it (e.g. by using extra=forbid). Whether you’re using either approach or a mix of both in your code, Pyrefly can pick it up automatically from how you’ve written your Pydantic model:

# Lax mode: We can pass extra fields to our model by default
class ModelAllow(BaseModel):
x: int

ModelAllow(x=1, y=2) # pyrefly won't report an error here

# Strict mode: we can forbid extra fields
class ModelForbid(BaseModel, extra="forbid"):
x: int

ModelForbid(x=1, y=2) # pyrefly will report an error here

Ultimately the value here is that you don’t have to manage external configuration files or plugins to get your type checker to work with Pydantic. This is a different approach compared to say Mypy - which requires you to install a separate Pydantic plugin and configure it via your mypy.ini or pyproject.toml file.

Getting Started​

There are no special configurations or plugins required to start using Pyrefly with Pydantic! The steps are as simple as:

1. Install Pydantic (preferably v2).
2. Install Pyrefly (v0.33.0 or later)
3. Write Pydantic models as usual.
4. Run Pyrefly / use it in your IDE

Simple as that! If you’d like to have a go playing around with a few examples, we created a demo repo that you can clone and try out.

Conclusion​

Pyrefly’s Pydantic support is experimental and evolving, so you may encounter edge cases or features that aren’t fully covered yet. We’d like to strongly encourage you to try out Pydantic support in your projects and let us know what works, what doesn’t, and what you’d like to see improved! Your insights and suggestions are invaluable in helping us refine this feature and prioritize enhancements. You can open an issue in our GitHub repo or connect with us on discord if you have feedback to share.

Looking ahead, we’re also working on expanding Pyrefly’s capabilities to support additional third-party Python packages that are widely used in the ecosystem. We’re currently focused on adding support for Django and SQLAlchemy, but if there’s a particular library or framework you rely on, please let us know! Your suggestions and feedback will directly influence our roadmap and help make Pyrefly even better for the Python community.

Today we’re thrilled to announce that we have reached Beta status for Pyrefly, our open-source, high-performance tool for Python code navigation and type checking! We first announced Pyrefly back in April 2025, and thanks to incredible community feedback and a ton of work from our team, we’ve hit a significant milestone.

But what does "Beta" mean for Pyrefly? This label can mean different things for different projects, for us it means we’ve made significant steps towards our goals for stability and production readiness. We’ll cover more of the specifics in this blog, but at a high level what this means is that when using a version of Pyrefly with Beta status (v0.42.0 or later) you can feel confident that:

• The IDE extension is ready for production use right now,
• The core type-checking features are robust, with some edge cases that will be addressed as we make progress towards a later stable v1 release.

🚀 The IDE Experience: Battle-Tested at Meta Scale​

A major priority for Pyrefly development since the beginning has been to deliver a lightning-fast and scalable IDE experience. Pyrefly was born out of a real-world production problem: Meta's Instagram developers were struggling with painfully slow code navigation, autocomplete, and type checking on their massive codebase.

Over the past year we’ve been rapidly adding new features and addressing bugs found by our passionate community of alpha testers (both internal and external). We're now proud to say Pyrefly is the default language server and type checker for all developers working on Instagram at Meta. By testing Pyrefly’s IDE extension on a codebase the size of Instagram we’ve been able to deliver hotly requested features with confidence that they will be reliable for large production codebases.

A few examples of Pyrefly’s latest language server features include:

Automatic import refactoring​

Pyrefly will now automatically update your imports when you rename or move a file.

Jupyter Notebook support​

You can now use Pyrefly with Jupyter notebooks for diagnostics (red squiggles), inlay hints, go-to-definition, hover, semantic tokens, signature help, and completions.

Third-party stubs shipped with the extension​

Language server features like hover and autocomplete are now available for third party libraries with Typeshed stubs. This support is available by default, without the need for a config file (pyproject.toml / pyrefly.toml), to provide a better out-of-the-box experience.

For a full list of supported IDE features check out the Pyrefly IDE documentation.

Better Type checking? Check ✅​

We've also made steady progress in improving Pyrefly's core type-checking engine since the Alpha release. Our focus has been on achieving higher conformance with the Python Typing Specification while also reducing false positives and improving support for modern Python patterns and popular libraries. In this section we'll highlight a few examples of the key fixes, new features, and design decisions that have paved the way for a more reliable type-checking experience in this Beta release.

Type Inference​

We understand writing type annotations can be tedious, so from the start Pyrefly has had some capabilities for automatically inferring types for returns and local variables and displaying them in the IDE. Since the first alpha release we’ve been steadily expanding inference capabilities, for example by improving our ability to infer the types of empty containers on first use:

from typing import reveal_type

def f[T](x: T | None) -> list[T]:
    return [x] if x else []

x = f(None)
x.append(1)

# Pyrefly is now able to infer that `x` has type `list[int]`.
reveal_type(x)

Type Narrowing​

We’ve added several new ways to narrow types and reworked type narrowing logic to prevent unwanted "pollution" of types after checks like isinstance:

from typing import Any, reveal_type

def f(x: Any):
    if isinstance(x, int):
        print(x)
    # Reworked type narrowing means the revealed type is now correctly `Any`,
    # not `int | Any` as it was previously.
    reveal_type(x)

Preliminary Support for Pydantic and Django​

We’ve added preliminary support for two of the most popular Python web/data libraries: Pydantic and Django. Pyrefly can now recognize key objects from these libraries and perform static analysis to catch potential errors before you ever run your code. This support works out-of-the-box with no configuration or plugins required, and includes IDE support.

Django Support​

As shown in this example, by default, Django automatically adds an id field to serve as the primary key (unless you define a custom primary key). Pyrefly is able to infer that the id exists and is of type int

from django.db import models

class Reporter(models.Model):
    full_name = models.CharField(max_length=70)
    # Django auto-adds: id = models.AutoField(primary_key=True)

reporter = Reporter()
reveal_type(reporter.id)  # Pyrefly infers: int

See more examples in the Pyrefly Django docs.

Pydantic Support​

In this example Pyrefly can read your Pydantic model’s configuration directly from your code to determine there is a type error where age should be an int not a string:

from pydantic import BaseModel, Field

class User(BaseModel):
    name: str
    age: int = Field(strict=True) # strict mode

# Pyrefly will report an error here.
y = User(name="Alice", age="30")

See more examples in the Pyrefly Pydantic docs

Dataclass Transforms Support​

An important addition that laid the foundation for supporting libraries like attrs and Pydantic, was allowing Pyrefly to recognize custom dataclass-like class transformations:

from attrs import define  # third-party `attrs` package

@define
class C:
    x: int

# `attrs` uses a dataclass transform, and Pyrefly now recognizes the
# auto-generated constructor based on the class attributes.
C(x=0)

🙌 An improved user experience​

We understand writing type annotations, dealing with strict checks, and configuring tools can be a barrier to adopting typed Python for many people, so we are always looking for ways to make using Pyrefly as painless as possible, dare we say even delightful? This section highlights some of the incremental improvements we've been working on to improve the overall user experience:

Type Error Message Improvements​

We’ve also cleaned up our error messages, making them clearer and providing embedded code snippets to pinpoint the exact location of the issue:

Before:

foo.py:1:5-15: `+` is not supported between `Literal[1]` and `Literal['oops']`

After (with snippet and detailed explanation):

ERROR `+` is not supported between `Literal[1]` and `Literal['oops']` [unsupported-operation]
 --> foo.py:1:5
  |
1 | x = 1 + "oops"
  |     ^^^^^^^^^^
  |
  Argument `Literal['oops']` is not assignable to parameter `value` with type `int` in function `int.__add__`

Smoother migration from MyPy or Pyright​

Different typecheckers display different behaviour, which can make it a challenge to switch from one to another. While it's not always possible to cleanly translate one config option to another, the pyrefly init command now does a better job of searching for an existing MyPy or Pyright configuration and transforming it into a pyrefly.toml (or [tool.pyrefly] section). You can find more details in the migration guides section of the Pyrefly docs.

A more configurable IDE experience​

Do you want type error diagnostics (i.e. the red squiggles) in your IDE or not? Do you want to use Pyrefly’s type errors but not other LSP features? Do you want to pick and choose specific language server features to enable? We know that how you set up your code editor is a personal choice, so we’ve added more configuration options to enable you to “choose your own adventure” with your Pyrefly IDE experience.

🔬 Enhancing Performance, Squashing Bugs and Aligning with the Spec​

We started developing Pyrefly with a clear goal in mind: make a tool that can statically analyze your code, catch type-related bugs, and do it much faster than existing tools like Mypy. While performance was good even in the early releases of Pyrefly, on the journey to Beta we’ve been focused on improvements for increasingly complex codebases, reducing type checking time and addressing edge cases for projects of varying size with many dependencies.

In some cases we’ve been able to reduce the time it takes to type check large projects with virtual envs, node-modules and other large dependencies by over 95% compared to earlier alpha versions of pyrefly. We've also closed over 350 bug issues opened by users and have been using the Python typing conformance test suite to benchmark our progress towards fully implementing the typing specification. So far we’ve gone from 39% conformant at alpha launch to over 70% conformant today.

There’s a lot more that’s been happening than we can possibly be squeezed into one blog post, so if you’d like to take a look back in more detail you can check out the completed beta milestone or our previous release notes.

What’s Next?​

This Beta release marks a significant milestone, but the journey isn't over! We’re now focusing on the further work that is needed to bring you a stable v1.0 release next year, including:

• Adding further support for popular third-party libraries (especially Django and Pydantic integration).
• Implementing the remaining missing features from the Python type system to reach 100% conformance.
• Making Pyrefly work even faster and consume even less memory
• Fixing more bugs!

We’d also like to say a huge thank-you to everyone who has helped get Pyrefly to this release. Whether you’ve contributed to the codebase, opened GitHub issues or just commented with your questions and feedback, your contributions have helped shape the direction of this project thus far. If you want to stay in the loop and continue being part of the conversation as we work towards Pyrefly v1.0 you can check out the GitHub repo or join our Discord community.

TL;DR:

• NumPy's type-completeness score was ~33%.
• A one-line fix doubled coverage to over 80%.
• Fully typing MaskedArray pushed the score to nearly 90%.
• What's left? Top-level numpy.ma functions, more precise overloads, and adding a type-checker to NumPy's CI.

Wait, what's type completeness?​

Modern IDEs use type annotations to help developers by showing them helpful suggestions and highlighting syntax. Pyright is a popular type-checker which, as well as checking for correctness and consistency, can also measure what percentage of a library's public API has type annotations. We call the percentage of fully-typed symbols exported by a library the type-completeness score.

For example, a module which exports functions foo and bar:

def foo(a: int):
    return None

def bar() -> int:
    return 1

would have a 50% type-completeness score, because:

• foo is partially unknown, as it's missing a return annotation.
• bar is type-complete.

By changing the foo signature to be def foo(a: int) -> None:, the type-completeness score would jump to 100%. The more type-complete a library is, the more helpful the suggestions an IDE can show to the user.

Note that type-completeness only measures how much of the public API (at least, the part known to Pyright) is covered by types. If you want to verify that those types are correct and self-consistent, you'll also need to run a type checker. The most used type checkers currently are mypy and Pyright, but Pyrefly and ty are also attracting a lot of attention due to their impressive performance characteristics (note however that neither yet describes itself as production-ready, so temper your expectations accordingly if you try them out!).

How type-complete is NumPy?​

When we started this effort (in March 2025), we first tried measuring NumPy's type-completeness by running:

pyright --verifytypes numpy

The output showed a completeness score of...18%. Wait, only 18%? This seemed very low, because by then typing efforts in NumPy had been ongoing for some time. Was something up with the metric? Upon closer inspection of the output, we noticed a few things:

• Some objects, such as DTypeLike, were reported to be "partially unknown", even though they had type annotations.
• The type-completeness report included test modules such as numpy.tests.test_matlib.

The first issue was caused by an import from the standard library decimal module, which itself is partially untyped. Given that this is outside of NumPy's direct control, we decided to exclude it from the coverage report by using --ignoreexternal, as suggested by Eric Traut.

For the second issue, Pyright gives us an option to export the coverage report to json (--outputjson). We could then parse the json and exclude numpy.tests. Given that NumPy users wouldn't ordinarily interact with NumPy's internal test suite but that Pyright considers it public, we decided that it made sense for us to exclude tests in order to focus our efforts on what would make the biggest user-facing impact.

Once we'd addressed the two steps above, the baseline type-completeness score became 33%. This was our starting point. We could then focus our efforts on the remaining 67%!

The one-line change which doubled type-completeness​

Pyright's report includes classes, methods, functions, type aliases, and more. A lot of scientific Python code centres around some central classes such as numpy.ndarray. ndarray was reported as "partially unknown", but eye-balling the exported symbols related to that class revealed something interesting:

>>> np.mean([x['isTypeKnown'] for x in exported if x['name'].startswith('numpy.ndarray.')])
np.float64(0.9811320754716981)

So, ndarray was reported as "partially unknown", but 98% of its methods had known types. It shouldn't be much effort to bring that number to 100%! In fact, all it took was a one-line change to fix a typo in a type annotation:

- def setfield(self, /, val: ArrayLike, dtype: DTypeLike, offset: CanIndex = 0) -> None: ...
+ def setfield(self, /, val: ArrayLike, dtype: DTypeLike, offset: SupportsIndex = 0) -> None: ...

That's it! CanIndex was an unknown symbol and was probably mistyped, and replacing it with the correct SupportsIndex one brought NumPy's overall type-completeness to over 80%! We then started examining other NumPy classes to see if there was anywhere else where we could make an impact, and hopefully a much larger one.

Enter MaskedArray​

When we looked at the percentage of typed symbols from the MaskedArray class, we noticed something interesting:

>>> np.mean([x['isTypeKnown'] for x in exported if x['name'].startswith('numpy.ma.core.MaskedArray.')])
np.float64(0.2)

Only 20% of them were typed! That's quite a contrast with ndarray, which was already at 98% when we started. It's also a fairly widely used class, appearing in the codebases of pandas, scikit-learn, and xarray. Given how poorly typed it was, we decided it would be a good candidate to spend time on!

Typing MaskedArray​

The main difficulty in typing NumPy code isn't inferring the possible argument values (which is quite easy to do with automated tools), but rather dealing with the large number of overloads. This is because many of NumPy methods' return types depend on the exact combinations of the input types. For example, suppose we have a MaskedArray ma and want to count the number of non-null values:

• ma.count() returns an integer.
• ma.count(axis=0) returns an array.
• ma.count(keepdims=True) also returns an array, of the same shape as the input array.

We can type this by having a different overload of each of these different cases. This is a relatively simple example, but there are others where the number of necessary overloads was as high as 9! This isn't something which is easy to automate, and requires careful reading of the documentation and of the source code. It's a non-trivial amount of work.

But...we pulled through it, and thanks to some very timely and constructive reviews from the amazing Joren Hammudoglu, MaskedArray is now reported as 100% type-complete! As for the overall type-completeness, that's now at 88%. So...what's left?

What's missing from NumPy?​

In the MaskedArray module, there's still some untyped top-level functions, such as numpy.ma.count. Overloads could be made more precise and shape-preserving (e.g. if the input is 2D, then make sure to preserve this fact in the output where possible). There's some missing defaults in the stubs. There's no shortage of work here.

The biggest missing bit, however, is the elephant in the room: NumPy doesn't run a type-checker over its codebase in CI. It has some typing tests, sure, but that's different from running a type-checker. If any motivated reader is interested in making a significant open source contribution, then getting NumPy's typing into a state such that a type checker (and possibly even stubtest) can be run over it could be a great use of your time.

Conclusion, acknowledgements​

We've looked at how we contributed towards increasing NumPy's type-completeness. Given how widespread NumPy's adoption is, we expect this effort to have been an impactful one. We look forward to seeing what else we can achieve in this space - thank you to Meta and Quansight Labs for having funded and facilitated this effort!

The challenges of managing ever-growing codebases are hardly new. As far back as 1995, Niklaus Wirth, (creator of programming language Pascal) already emphasized the importance of keeping software lean in his essay A Plea for Lean Software. Fast forward to today: many programmers still face the reality that, despite their best coding intentions, as projects grow in size and complexity, so do their codebases. Even when a project scales to millions of lines of code, developers still expect their IDE to be fast, accurate, and efficient. And with increasingly large and interconnected (dare I say, spaghetti?) code, you probably rely on your IDE even more to help you navigate the chaos (ahem I mean complexity).

But what you may not have thought about before is that scaling project size presents a real challenge for your IDE: how do you keep code navigation tools responsive and reliable when the codebase keeps expanding? In this blog, we’ll explore this challenge and introduce you to Pyrefly - a scalable language server and typechecker designed to keep your Python development experience smooth and snappy at scale.

Background - What is a Language Server and Why Does It Matter?​

The Language Server Protocol (LSP) is a standardized way for code editors to communicate with language-specific servers that provide features like autocomplete, go-to-definition, and symbol renaming. Instead of each editor implementing these features separately, LSP allows a single language server to support multiple editors. Pyrefly’s language server capabilities are based on the Language Server Protocol Specification and are designed to still be blazing fast even on code bases with over 20 million lines of code.

A key capability of many language servers, including Pyrefly, is typechecking, which enhances IDE features by providing type diagnostics. Pyrefly’s language server not only reports type errors like basic type checkers, such as Mypy, but also replaces core IDE functionalities including “find definition,” hover (displaying types and docstrings), and completions. By consolidating these features, Pyrefly ensures that the types it checks and the types displayed in your IDE will always match.

Instagram - A Case Study on the Pain of Slow Code Navigation​

Meta operates an incredibly large Python codebase - a massive monorepo containing almost 1.5 million Python files maintained by thousands of developers. Instagram is one of those projects, with over 20 million lines of Python code. At this scale, even simple navigation tasks like jumping to a function definition, searching for references, or loading syntax highlights could take almost a minute in the worst cases. That may not sound like a lot on its own, but experiencing it every few minutes quickly becomes frustrating and has a tangible impact on developer productivity, especially when multiplied across a large company like Meta.

Pyrefly emerged in part to address this exact challenge (you can read more about our origin story in our intro blog). In real world use cases, developers who switched from Pyright (the default LSP for VSCode) to Pyrefly spent 98% less time waiting on hover results and go-to definition was ~10x faster. On the slowest files (p99), these IDE responses grew from an order of minutes to seconds (30x improvement). If those numbers are hard to visualise, the TL;DR is that this upgrade took instagram developers from questioning “is my editor frozen?” to not giving their IDE a second thought.

Pyrefly (left) vs Pyright (right) autocomplete speed comparison

These early results are certainly promising indications of a smoother developer experience for Meta engineers, and we're excited to share more insights as developers continue using Pyrefly. But Pyrefly isn’t just for Meta developers, it’s open source and ready for everyone to explore! If you’re curious about Pyrefly’s language server features and want to see how to get it up and running in your IDE, keep reading!

Pyrefly LSP at a Glance​

While Pyrefly is still in Alpha as of the time of posting, it already supports most of the essential IDE capabilities that Python developers rely on daily, such as:

• Autocomplete: predicts what you’re likely to type next, reducing the need to remember exact names of variables, functions, and others, even importing them automatically for you
• Go to Definition: allows you to jump directly to the source of a function, class, or variable with a single click.
• Hover: when you hover over a symbol, Pyrefly displays useful information such as type annotations, documentation, and inferred types.
• Rename symbols: right click to rename variables, functions, or classes across the entire codebase.
• Typechecking: Pyrefly will also show type errors and infer types, which you can toggle on or off in your Pyrefly settings (more info in the next section)
• And many more! explore the full list and details in the Pyrefly IDE docs.

The Pyrefly team and our open-source community are continuously working on improvements and new features so stay tuned for updates! We also want to hear from you - what features do you need to make your IDE experience better? Open a GitHub issue or join our discord to share your thoughts.

How to add Pyrefly to your IDE​

Pyrefly can be used in a range of IDEs, including standard GUI editors like VSCode or Pycharm, terminal editors like Neovim or Emacs, and AI editors like Cursor or Windsurf. You can check out the full list of supported IDEs in the Pyrefly IDE docs.

For GUI editors, setup is pretty straightforward and generally follows the same steps:

1. Search for “pyrefly” in the appropriate extension marketplace for your IDE and install it
2. Open any Python file and the extension will activate automatically
3. Note: if using an editor other than VSCode you may need to uninstall the default Python LSP in your editor. You can do this by opening your extension settings and setting "Language Server: None"
4. Optional: we recommend all developers use a typechecker as part of their regular software development process, however we know that type errors in your IDE can be noisy, so the type errors feature is not turned on by default if you don't have a pyrefly.toml (from pyrefly init). If you DO want type errors to show up in your editor everywhere (as red squiggles), you should update your extension settings to include "python.pyrefly.displayTypeErrors": "force-on"

For terminal editors the setup process can vary depending on which editor you use so check out the installation documentation for specific instructions.

Conclusion​

As Python projects continue to grow in size and complexity, having a fast, reliable, and scalable language server is essential for maintaining developer productivity (and our sanity to be honest). So if you’re working on a large codebase and want an LSP designed with scalability in mind we invite you to give Pyrefly a try!

While the project is still in Alpha we’re especially eager to hear from more users like you about how the IDE extension performs on real world codebases. If you have any feedback, bug reports or feature requests please feel free to open a GitHub issue, and if you have any questions or need support please come chat with us on Discord!

Happy coding, fellow pyreflies! 🔥🪰

Python is one of the most successful programming languages out there, with it recently overtaking Javascript as the most popular language on GitHub, according to the latest GitHub Octoverse report. The report emphasises the popularity of the language in the growing fields of AI, data science and scientific computing - fields where speedy experimentation and iteration are critical, and where developers are coming from a broad range of STEM backgrounds, not necessarily computer science. But as the Python community expands and projects grow from experiments to production systems, that same flexibility can become a liability.

That’s why today we’re going to talk about typed Python - what it is, why it’s become important for Python developers today, and how to get started using it to write higher quality, more reliable code.

What is Typed Python?​

Before we dive into why you should be using typed Python in your daily development lives, first we need to understand some core concepts and how we got here.

Dynamic vs static typing​

The classic Python programming language that you know and love is dynamically typed. What does that mean exactly? It means that types are determined at runtime, not when you write your code. Variables can hold any type of value, and you don't need to declare what type they are.

Here’s an example of dynamic typing in action:

x = 5        # x is an integer
x = "hello"  # now x is a string
x = [1,2,3]  # now x is a list

This behaviour is one of the things that sets Python apart from languages that are statically typed, like Java or C++, which require you to declare types from the get go:

int x = 5;
std::string x_str = "hello";
std::vector<int> x_vec = {1, 2, 3};

In the above example we can’t just reassign the variable x to a value of whatever type we want, it can only hold an integer because of the static typing nature of the C++ language.

The fact that Python is a dynamically typed language is one of the reasons it is so easy to use and popular amongst new and experienced programmers alike. It makes it easy to develop quick demos, experimental research and proof of concepts, without needing to spend precious development time declaring types. This flexibility has been instrumental in Python's adoption in AI, data science, and scientific computing, where researchers need to rapidly iterate and experiment with different approaches.

However… (surely you knew there was a “but” coming?)

We are quickly moving past the “proof-of-concept” phase for many of these industries. AI and machine learning efforts are actively being integrated into production applications, and with that comes production-level expectations of reliability and stability. Relying on dynamic typing opens these codebases up to a certain level of risk that may not be acceptable at the scale they are now expected to operate.

Enter PEP 484: Static Typing Comes to Python​

Cast your mind back to September 2014: Germany has just won the world cup, skinny jeans are still in fashion and Taylor Swift’s “Shake it Off” is number 1 on the charts. That same month PEP 484 was first created, proposing the addition of type hints to Python, and fundamentally changing how future developers would be able to write and maintain Python code.

With PEP 484’s acceptance and introduction in Python 3.5, developers could now use static type annotations to declare the expected data types of function arguments and return values, and subsequent PEPs have continually added more features to expand and refine Python's type system. Today you can write statically typed Python statements like this:

def my_func(x: int, y: str) -> bool:
    z: str = str(x)
    return z == y

The key innovation of PEP 484 was introducing a gradual type system that allows developers to slowly add type annotations over time without breaking existing code. The system works by:

• Only type-checking functions that have explicit return or parameter annotations
• Introducing the Any type as an escape hatch that has all possible attributes
• Assuming untyped functions implicitly return Any

This approach has meant developers can incrementally adopt typing, while still allowing them to take advantage of the default dynamic typing approach that makes Python so easy to work with and ideal for quick prototyping.

Benefits of Python Type Hints: Write Better Code, Faster​

So why specifically should you start using type hints in your Python code? Python type hints offer a range of advantages that can significantly improve the quality, maintainability, and scalability of your codebase, at the same time making it easier for other developers to understand your code and collaborate with you.

Types help you catch bugs early​

Type hints assist static analysis tools in identifying mismatches and potential errors before the code is executed, allowing for early bug detection. Take the following example:

def add_numbers(a, b):
       return a + b
...
add_numbers(3, "4")  # Potential error

The above error might be easy to spot when you’re calling the function so close to where you’re defining it, but imagine you’re working across multiple files and/or with many lines of code separating them - suddenly it’s not so easy!

In comparison, if you’re using type hints in conjunction with a typechecking tool (such as Pyrefly or MyPy), you can catch this error much earlier - when you’re actually writing the code, rather than when it fails at runtime:

def add_numbers(a: int, b: int) -> int:
  return a + b
...
add_numbers(3, "4")  # a typechecker will catch this error at time of writing

Using a typechecker to highlight these types of errors also ensures you can catch an error like this even if you’ve missed this code path in your unit tests.

Typed code is self-documenting​

Another benefit of writing typed Python is that using function signatures and variable annotations provide clarity of intent for a given piece of code. In other words, it makes code easier to read and review. It makes refactoring safer and more predictable. It even helps new team members get up to speed quickly on what’s going on in your codebase without wasting their own time, or yours!

Take the following example, without type hints you have to carefully read the internal function code to understand what type of parameters will work and what will be returned:

def calculate_stats(data, weights):
    total = 0
    weighted_sum = 0
    for i, value in enumerate(data):
        if i < len(weights):
            weighted_sum += value * weights[i]
            total += weights[i]
    avg = weighted_sum / total if total > 0 else 0
    return avg, len(data)

With this version, you can tell instantly what type of arguments you should be passing and what you should expect to get back - saving precious dev time and just generally making your life easier:

def calculate_stats(data: list[float], weights: list[float]) -> tuple[float, int]:
    total = 0
    weighted_sum = 0
    for i, value in enumerate(data):
        if i < len(weights):
            weighted_sum += value * weights[i]
            total += weights[i]
    avg = weighted_sum / total if total > 0 else 0
    return avg, len(data)

I know I know - ideally all developers should be adding clear docstrings with every function they write, but we know in reality it doesn’t always shape up that way! Adding type hints is quicker than writing a typical docstring, won’t go stale (if enforced using a typechecker) and is better than no documentation at all. Modern Python typecheckers also have IDE extensions that include autocomplete functionality to make life easier.

Typed Python helps you scale from proof-of-concept to production-ready​

One of the most important benefits of using type annotations in your code is that it helps you scale your code faster and with less risk. For developers today, the pipeline from experimental code to production systems moves faster than ever, especially in AI and machine learning workflows where research prototypes must quickly evolve into robust, scalable applications.

For example, say there is a team of data scientists that has just published their findings and now needs to operationalize their models. If their published code already includes type hints it makes it much easier, quicker and safer for an engineering team to step in and integrate that research into production applications. In situations like these, type annotations act as a contract between different stages of development, making it clear how data flows through complex, multi-step processing pipelines. This is particularly valuable in AI workflows where a single type mismatch, like passing a NumPy array where a PyTorch tensor is expected, can cause silent failures or performance degradation that only surfaces under production load.

Get Started with Typed Python today!​

So now you know what typed python is and why you should be doing it, how can you actually get started adding types to your code?

Step 0 - start early!​

As a general rule of thumb, the earlier in a project you start adding type annotations the better. Type hints are much easier to add as you go than to retrofit across an entire codebase later.

As we’ve mentioned before, one of the great benefits of Python is that its dynamic typing default makes it very flexible and easy to get started with. So when you’re doing your initial experimentation and prototyping maybe you’re not thinking about making sure it’s type safe - and that’s ok! But as soon as you start to think your project might be going somewhere, if more than one person might be working on it, using it or just reading it, you should start adding type hints.

Step 1 - install a type checker​

Choose and install a type checker that fits your needs. Typecheckers leverage the code annotations you write to provide important errors and warnings to ensure your codebase is type safe.

At Meta, we recommend Pyrefly, our new open-source type checker built in Rust. Pyrefly is designed to scale from small projects to massive codebases incredibly fast, while providing excellent developer experience. Read the Pyrefly documentation to understand configuration options and best practices, then start adding simple type hints to new functions before gradually working your way up to more complex scenarios.

You should also consider working with a typechecker that supports IDE integration to get real-time feedback as you write code. Pyrefly provides extensions for editors like VS Code, PyCharm, and Vim which will highlight errors and provide autocomplete suggestions based on your type annotations.

Adding your typechecker to your CI processes is also valuable for maintaining code quality at scale. You can configure your CI/CD pipeline to run type checking on every pull request, treating type errors as build failures.

Step 2 - make use of resources to get better at typing​

Typing is one of those skills that gets better the more you practice it in your code, but there are also great resources out there for getting to grips with the functionality and diving deeper into the concepts:

• Official Python typing documentation - The typing module docs provide comprehensive coverage of all available types
• PEP 484 and related PEPs - Understanding the foundational specifications helps you grasp the "why" behind typing decisions
• Documentation for your chosen typechecker, e.g. Pyrefly Docs on learning typing
• Join community forums and get support, e.g. Pyrefly Discord, Typing Discourse

Conclusion​

So there you have it - a quick trip around the world of Python typing! By now you’ve hopefully learnt that type hints aren't just another Python feature to add to the long list of things you’ll definitely get round to implementing eventually - they're a practical investment in your code's future. The upfront effort of adding type hints pays dividends in reduced debugging sessions, smoother code reviews, and fewer production issues. Most importantly, they give you the confidence to refactor and scale your codebase without fear of breaking things in unexpected ways. Start small by adding type annotations to your next function, add a type checker to your workflow, and before you know it writing typed Python will be second nature. Your future self (and your users and teammates!) will thank you.

Today we are announcing an alpha version of Pyrefly, an open source Python typechecker and IDE extension crafted in Rust. Pyrefly is a static type checker that analyzes Python code to ensure type consistency and help you catch errors throughout your codebase before your code runs. It also supports IDE integration and CLI usage to give you flexibility in how you incorporate it into your workflow.

The open source community is the backbone of the Python language. We are eager to collaborate on Pyrefly with the community and improve Python’s type system and the many libraries that we all rely on.

Get started​

Ready to dive in? The official Pyrefly website has all the details, but to quickly get started:

• Install Pyrefly on the command-line: pip install pyrefly.
• Migrate your existing type checker configuration to Pyrefly.
• Enhance Your IDE: Download the Pyrefly extension for VSCode and enjoy a lightning fast IDE experience from starter projects to monorepos.
• Leave feedback for us on GitHub.

Why we built Pyrefly​

Back in 2017, we embarked on a mission to create a type checker that could handle Instagram’s massive codebas of typed Python. This mission led to the birth of the Pyre type checker, inspired by the robust designs of Hack and Flow, and written in OCaml to deliver scalable performance.

Over the years, Pyre served us well, but as the type system evolved and the need for typechecking to drive responsive IDE emerged, it was clear that we needed to take a new approach. We explored alternate solutions and leveraged community tools like Pyright for code navigation. But the need for an extensible type checker that can bring code navigation, checking at scale, and exporting types to other services drove us to start over, creating Pyrefly.

The principles behind Pyrefly​

Today, we’re excited to unveil Pyrefly, a project we’ve been developing openly on GitHub. We invite you to explore our work and try it out on your own project. While a project like Pyrefly is the sum of thousands of technical choices, a few notable principles we’ve followed are:

Performance​

We want to shift checks that used to happen later on CI to happening on every single keystroke. That requires checking code at speed (on large codebases we can check 1.8 million lines of code per second!) and careful thought to incrementality and updates. Pyrefly is implemented in Rust and designed for high performance on codebases of all sizes.

IDE first​

We want the IDE and command line to share a consistent view of the world, which means crafting abstractions that capture the differences without incurring unnecessary costs. Designing these abstractions from the beginning is much easier than retrofitting them, which we tried with Pyre.

Inference​

Some Python programs are typed, but many aren’t. We want users to benefit from types even if they haven’t annotated their code – so automatically infer types for returns and local variables and display them in the IDE. What’s more, in the IDE you can even double click to insert these inferred types if you think that would make the program better.

Open source​

Python is open source, and hugely popular. The Python typing specification is open source, which made Pyrefly vastly easier to develop. Many of the libraries Meta contributes to are open source,( e.g., PyTorch).

Pyrefly is also open source, available on GitHub under the MIT license, and we encourage pull requests and issue reports. We also have a Discord channel for more free flowing discussions. We would love to build a community around Pyrefly.

The future of Pyrefly​

We will work with the Python community to drive the language forward and improve the developer experience. Since the beginning of Pyre, we open sourced our code and contributed a number of PEPs alongside the community of type checker maintainers. We feel we can do more with Pyrefly to help Python developers leverage the benefits of types for developers, library authors, and folks just learning the language.

Meta has leveraged types in dynamic languages from the beginning and knows the significant benefits it brings to developer productivity and security. We plan to share more of our learnings and tooling with blogs, better types in the ecosystem and language enhancements.

Today we’re releasing Pyrefly as an alpha. At the same time, we’re busy burning down the long-tail of bugs and features aiming to remove the alpha label this Summer. Your feedback is invaluable to get there, so please give it a try and report your bugs or things you think can be improved. Even if Pyrefly isn’t right for your project, we would love to hear how you use types and what you would like to see improved in your editor.

Join us on the journey as we help illuminate your bugs with Pyrefly. Happy coding! 🐍✨

Hear more about Pyrefly​

Check out the episode of the Meta Tech Podcast where several team members share their experience developing Pyrefly and technical details for how it works. We also just talked at PyCon US about high-performance Python through faster type checking and free threaded execution.

To learn more about Meta Open Source, visit ouropen source site, subscribe to our YouTube channel, or follow us on Facebook, Threads, X, and LinkedIn.

Acknowledgements​

Pyrefly was created By Meta’s Python Language Tooling Team: Jia Chen, Rebecca Chen, Sam Goldman, David Luo, Kyle Into, Zeina Migeed, Neil Mitchell, Maggie Moss, Conner Nilsen, Aaron Pollack, Teddy Sudol, Steven Troxler, Lucian Wischik, Danny Yang, and Sam Zhou.