Meta’s Python type checker Pyrefly has reached v1.5, and it is a big one: the release announcement says Pyrefly now passes all 146 test files in the Python typing conformance suite and checks 40% faster than v1.4.1 with 9% less memory. It also adds a new hint severity and several behaviour changes that can surface new errors after you upgrade.

This tutorial shows how to install Pyrefly 1.5, configure the new severities, deal with the behaviour changes, and upgrade a large codebase without a wall of red.

What’s new in Pyrefly 1.5

From the official blog post and the v1.5.0 release notes:

  • Full typing spec conformance. Pyrefly passes all 146 files in the conformance suite, the reference tests for the typing specification.
  • Faster checks. Across 71 projects in Astral’s ty_benchmark and the python-type-checking benchmark, the geometric mean of wall time is 0.60x of v1.4.1, CPU time 0.65x and memory 0.91x. The team measured these on an M5 Max MacBook Pro with 18 threads.
  • A hint severity. Diagnostics that used to be IDE-only (unused-import, unused-parameter, unused-variable, unreachable, inactive-code) are now regular error kinds you can configure.
  • Library support. Pydantic model_validate and model_construct calls are type checked; Django model fields and managers get more accurate types; SQLAlchemy select().filter_by() checks field names and value types.
  • Editor features. A “Type source” section in hover, class hierarchy CodeLens, quick fixes to insert inferred annotations, and parameter-name inlay hints.

Release executables are now built with profile-guided optimisation, and Linux x86-64 builds are also optimised with BOLT.

Step 1: Install or upgrade

pip install --upgrade pyrefly==1.5.0
pyrefly --version

With uv you can run it without adding it to your project:

uvx [email protected] check

If you’re new to Pyrefly, pyrefly init creates a config for you. In 1.5, when init finds a BasedPyright baseline, it offers to create a Pyrefly baseline too, so a migrated project starts with a clean check.

Step 2: Understand the new hint severity

Before 1.5, unused imports and unreachable code only appeared in your editor and you couldn’t control them. Now they are error kinds with the default severity hint:

  • In your editor, hints appear as usual.
  • In pyrefly check output, hints are hidden by default.

Because they are now error kinds, you can promote them. For example, to fail CI on unused imports, add this to pyrefly.toml:

[errors]
unused-import = "error"
unused-variable = "warn"

In pyproject.toml, the same settings go under [tool.pyrefly.errors]:

[tool.pyrefly.errors]
unused-import = "error"

You can also silence a single line with a suppression comment, the same way as any other Pyrefly error:

import os  # pyrefly: ignore[unused-import]

Note one change in defaults: unreachable is now a hint instead of warn, so it disappears from command-line output. If your team relied on seeing it in CI, set it back:

[errors]
unreachable = "warn"

Step 3: Expect warnings in pyrefly check

pyrefly check now prints warnings by default. These include uses of deprecated APIs, redundant-cast and unnecessary-type-conversion. Warnings don’t change the exit code, so CI won’t break, but your logs will get longer.

To keep the old, quieter output:

pyrefly check --min-severity=error

or in config:

min-severity = "error"

Step 4: Watch for the annotation scoping change

This is the change most likely to produce surprising new errors. To match the typing spec, postponed annotations now look up names in the enclosing class body first. Postponed annotations include string annotations, anything under from __future__ import annotations, and stub files.

Here is a small example that behaves differently in 1.5:

from __future__ import annotations


class Converter:
    value: int  # In 1.5 this "int" refers to the method below

    def int(self) -> int:
        return 42

Because the class defines a method named int, the annotation value: int now resolves to that method, even though the method is defined after the attribute, so expect Pyrefly to flag this code after upgrading. The fix is to refer to the builtin explicitly:

from __future__ import annotations
import builtins


class Converter:
    value: builtins.int

    def int(self) -> builtins.int:
        return 42

Pyrefly 1.5 also reports uninitialised names in eagerly evaluated annotations and illegal circular references in annotations.

Step 5: Check the right files

Another behaviour change: pyrefly check <dir> now honours config excludes. A directory argument uses the config found from that directory and respects its project-excludes. So pyrefly check . checks the same files as plain pyrefly check.

If your CI script passed paths to force-check excluded folders, those folders are now skipped. To apply excludes even to explicit file paths, use the new --force-exclude flag. To add excludes without editing the config, use --extend-project-excludes.

Also new: a required-version mismatch now exits with code 4 instead of 1, so a script can tell “wrong Pyrefly version” apart from “type errors found”:

pyrefly check
status=$?
if [ "$status" -eq 4 ]; then
  echo "Pyrefly version does not match required-version in config"
fi

Step 6: Upgrade a big codebase safely

The release notes include a recommended loop for silencing new errors so you can fix them gradually:

pyrefly check --suppress-errors
# run your formatter, e.g. ruff format .
pyrefly check --remove-unused-ignores

Repeat until both the formatter and the type check are clean. This adds # pyrefly: ignore comments where new errors appear, so you can merge the upgrade now and burn them down later. Put the upgrade in its own pull request so reviewers can see exactly which suppressions were added.

Useful new checks to try

Several new error kinds are opt-in, which makes them good candidates for stricter modules:

Error kind What it reports
explicit-any-use Places where explicit Any is used
partially-unknown-type Types that are only partly known
protected-access Access to _private members from outside their class
invalid-format-spec f-string format specs that don’t match the value’s type

Two new warnings are on by default: unexpected-never, for functions that can never return but aren’t annotated NoReturn or Never, and fallback-search-path-relative-import, for imports that only resolve through a heuristic and may fail at runtime.

Example of a format-spec bug the opt-in check can catch:

def show(name: str) -> str:
    return f"{name:.2f}"  # a str value with a float format spec

Enable it in config:

[errors]
invalid-format-spec = "error"

Better Pydantic and Django checking

If you use Pydantic, model_validate and model_construct calls are now checked, and constructor checks follow Pydantic’s lax-mode coercion more closely. That should remove false positives for enums, named tuples and NewTypes:

from pydantic import BaseModel


class User(BaseModel):
    id: int
    email: str


user = User.model_validate({"id": 1, "email": "[email protected]"})
reveal_type(user)  # User

For Django, model fields and managers have more accurate types, including fields accessed on the class, custom id primary keys and querysets from Manager.as_manager(). Pyrefly also now gives module names to files like 0001_initial.py migrations.

How it compares on speed

The Pyrefly team also ran ty’s benchmark of 18 projects against ty 0.0.107, mypy 2.4.1 and Pyright 1.1.414. They report Pyrefly as 13x faster than mypy and 25x faster than Pyright (geometric mean of wall time), and roughly even with ty: faster on some large projects such as pytorch and sympy, slower on most smaller ones by milliseconds. As always, benchmark on your own repo before switching tools.

Takeaway

Pyrefly 1.5 is a worthwhile upgrade: full spec conformance means fewer tool-specific surprises, and the speed-up is noticeable on large projects. Before you upgrade, plan for three things: warnings now show in pyrefly check, unreachable became a hint, and class-body name lookup in postponed annotations can flag new errors. Use --suppress-errors and --remove-unused-ignores to land the upgrade quickly, then turn on hint and opt-in checks module by module.