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
hintseverity. 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_validateandmodel_constructcalls are type checked; Django model fields and managers get more accurate types; SQLAlchemyselect().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 checkoutput, 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.
