pyrefly

Release date: September 28, 2026

About dev releases
Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.4.0-dev.2 bundles 493 commits from 20 contributors.

⚠️ Notable change: X | None annotations with an unknown X

Pyrefly now decides whether | builds a type union from the type-form context of the expression, instead of from the types of its operands. Before this change, an annotation such as UnresolvedType | None (for example, when UnresolvedType comes from a missing import) was evaluated as plain Unknown, and the | None was silently dropped. Pyrefly now evaluates it as Unknown | None.

This is more correct, but it can surface new errors, such as missing-attribute on None, in code that uses unresolved types in Optional-style annotations. Please try this dev release and report any false positives. (#4846)

✨ New & Improved

Type Checking

• Pyrefly now respects the stdlib/VERSIONS file of a custom typeshed, and it notices when that file changes.
• Build systems can now supply a default configuration.
• Unreachable-code reporting is more precise: Pyrefly reports dead code after a run of with statements, branches that are decided by the type of their test, and except clauses that can never match.
• Pydantic Strict types, such as StrictInt, now enable strict mode for the field.
• TypeVarTuple variance is now checked.
• NewType over an abstract class no longer produces a false-positive bad-instantiation error.

Language Server

• The status indicator refreshes when a pyrefly.toml file is added or removed, and Pyrefly rewatches files when an explicitly configured config file changes.
• The TSP initialize response now includes serverInfo.
• In a match value pattern, attribute completion now ranks enum members that earlier case arms already cover lower.
• Baseline matching supports a new column-ordered mode, and the language server matches baselines in batches.

Other

• Pyrefly now has an experimental programmatic API for Monty.
• When some warnings are hidden, the message now explains how to show them.
• Memory usage and commit latency in the incremental state are improved.

🐛 Bug fixes

• #4846: Fixed regressions from v1.3.0 in type inference after a variable is reassigned to Any. See also the notable change above.
• #4858, #4618: Enum.value no longer widens a literal value to its base type (for example, to str).
• #4400: Pydantic private attributes (PrivateAttr) are no longer treated as frozen.
• #4995: Django models now give pk the correct type when the primary key is a ForeignKey(..., primary_key=True).
• #4991: pyrefly suppress now writes # pyrefly: ignore[code] without a space before the bracket, which matches the documentation.
• #4986: Hover now works on attribute assignments in __init__.
• #4813: Pyrefly no longer rejects a duck-typed Mapping in a ** dict unpacking.
• #4650: stubgen no longer keeps the full analysis of the whole import closure in memory.
• #4592: A __get__ overload with a self type of Concatenate[ObjT, P1] and a sibling TypeVar now matches correctly.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.4.0-dev.2

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@stroxler, @connernilsen, @rchen152, @kinto0, @asukaminato0721, @samwgoldman, @jakevdp, @yeetypete, @MarcoGorelli, @grievejia, Abby Mitchell, @Pager-dot, @arthaud, @digvijaysai29, David Tolnay, @yangdanny97, @Aniketsy, @QEDady, @alexander-beedie, Alan Kurusingal

🔬 Tensor Shape Support

JAX stub support is still under development and is not yet available on PyPI. The JAX improvements below describe ongoing work in the repository rather than an installable stub package in this release.

• Torch shape stubs cover much more of the public API, including more pointwise, reduction, indexing, FFT, pooling, convolution, and attention operations, and they report unknown top-level Torch APIs.
• A new IntVar[N] runtime wrapper supports dimension arithmetic. Bare *tuple[...] and *IntTuple splats are now accepted in shapes.
• JAX and NumPy stubs have improved shape inference for random, lax, pad, split, expand_dims, and other operations, and the top-level jax namespace now has stubs.

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: September 18, 2026

About dev releases
Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.4.0-dev.1 bundles 98 commits from 13 contributors.

✨ New & Improved

Type Checking

• A new opt-in uninitialized-instance-variable check reports instance attributes that may be read before assignment, including fields on dataclasses declared with init=False.
• Overload inference now handles generic call targets and callable fallbacks more precisely, including functools.partial, independently pruned arguments, and writable callback variance.
• Property getters, setters, and deleters with extra required parameters now report invalid signatures when the decorator is applied.
• Unaliased directory imports now bind the imported name correctly, and source files nested beyond the configured analysis depth are rejected cleanly.
• Django annotate() calls now add their declared attributes to the resulting queryset type.

Language Server

• Hover information now prefers interface docstrings when available and falls back consistently to implementation docstrings across imports.
• Parameter-name inlay hints now align correctly for bound methods whose receiver is named __self.

🐛 Bug fixes

We closed 3 bug issues this release 👏

• #4918: Property decorators now reject getters, setters, and deleters with extra required parameters instead of silently accepting invalid signatures.
• #4936: Fixed shifted parameter-name inlay hints for bound methods whose receiver is named __self, such as methods on loguru.Logger.
• #1610: SQLAlchemy dataclass fields now reject mutable dict, list, and set literals passed to mapped_column(default=...) and recommend default_factory instead.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.4.0-dev.1

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@rchen152, David Tolnay, @dependabot, @Kylei, @dedsec-terminal, Oleh Prypin, Gábor Varga, @jakevdp, @jasonnathanieln, @stroxler, @ndmitchell, @connernilsen, @asukaminato0721

🔬 Tensor Shape Support

JAX stub support is still under development and is not yet available on PyPI. The JAX improvements below describe ongoing work in the repository rather than an installable stub package in this release.

The current einops stubs are limited to Torch tensors. We are still exploring how to support multiple array packages.

• JAX NumPy, linear algebra, and FFT APIs now accept ArrayLike inputs more broadly, with improved shape inference for linspace, logspace, and geomspace.
• JAX, NumPy, and PyTorch constructors now preserve shapes derived from nested list literals, including zero-sized dimensions.
• Torch shape stubs now expose public submodules as attributes and support the single-argument and keyword forms of torch.where and bare @torch.no_grad.
• Shape-aware einops stubs now cover the remaining public APIs for Torch tensors.
• pyrefly-shape-extensions now supports Python 3.10 and provides runtime markers for regular nested lists.

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: September 28, 2026

Pyrefly v1.3.2 is a patch release that fixes regressions in how Pyrefly infers the type of a variable after it is assigned a value of type Any.

🐛 Bug fixes

• #4846: Fixed several regressions from v1.3.0 in type inference after a variable is reassigned to Any:
  • Assigning an implicit Any (a value with no known type, such as the result of an unannotated function or an unresolved import) to an annotated variable once again produces Unknown. It no longer turns into an explicit Any.
  • When a variable annotated as Optional[T] or T | None is narrowed to None and then reassigned inside that branch, Pyrefly no longer adds the annotation's None back after the branch. For example, x: Any | None followed by if x is None: x = get_any() now gives Any instead of Any | None.
  • When a variable's annotation is a union that contains Any, assigning Any to it now narrows the variable to Any. For example, x: Any | None followed by x = x or get_any() now gives Any instead of Any | None, so later attribute access no longer reports a false missing-attribute error on None.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.3.2

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

Release date: September 14, 2026

Pyrefly v1.3.1 is a patch release with a single bug fix.

🐛 Bug fixes

• #4909: Fixed a critical issue where Pyrefly would immediately crash on startup with a thread panic when empty or relative base paths were encountered during configuration. The server now safely resolves these paths against the working directory, preventing the crash and allowing normal operation.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.3.1

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

Release date: September 10, 2026

Pyrefly v1.3.0 bundles 934 commits from 71 contributors.

🔍Release Highlights

Type Checking

• New diagnostics and more accurate type inference. Pyrefly now catches invalid literal regular expressions, invalid mock.patch targets, unsupported dataclass_transform arguments, incompatible Protocol.__call__ overrides, and unimplemented abstract methods. Pattern-match exhaustiveness, overload resolution, narrowing, and generic inference are also more accurate.
• Better support for major Python frameworks. Pyrefly understands same-file Django reverse relationships, checks SQLAlchemy updates against model fields, and recognizes attributes registered on PyTorch modules.

Language Server

• Search the whole workspace for methods and nested definitions. Workspace symbol search now covers methods, nested classes and functions, and class attributes even in unopened files.
• New editor refactorings and quick fixes. Change Signature updates a function and its call sites together, while new quick fixes remove unused imports and insert assert x is not None. Inlay hints can also insert required imports and link to definitions.

Configuration & CLI

• Target individual Pyrefly errors with standard suppression comments. # type: ignore[pyrefly:<code>] suppresses a specific Pyrefly diagnostic without hiding unrelated errors on the same line.
• Choose how Pyrefly handles untyped dependencies. The new --replace-untyped-imports-with-any option replaces selected third-party packages that lack stubs or a py.typed marker with Any, and pyrefly init translates mypy's follow_untyped_imports setting automatically.
• Baseline files are easier to maintain and review. Baselines can match by concise description instead of source position, use a compact format, show existing errors at reduced severity, remove stale entries with --prune-baseline, and reject them in CI with --error-stale-baseline.

Experimental Extensions

• Much broader shape-aware JAX and NumPy support. New JAX stubs cover array creation, manipulation, and linear algebra, while the new pyrefly-numpy-stubs package brings shape checking to NumPy. These stubs use a new type-level shape DSL, which replaces the old @shaped_array API.
• Expanded Polars and pandas DataFrame schema support. Pyrefly tracks Polars schemas through common DataFrame transformations, with support for typed Series and schema annotations. pandas columns= projections now preserve the requested schema as well.

✨ New & Improved

Type Checking

• Pattern matching gained stronger exhaustiveness checking, including tuple subjects and open types such as unions. Open-type exhaustiveness now has its own configurable non-exhaustive-match-open-type error kind.
• Overload selection now follows the latest typing specification more closely, producing a safe common return type for gradual arguments and reducing false positives in complex overloads.
• Type inference and narrowing are more precise for membership tests, equality checks, hasattr, wide Literal unions, callable values, reverse tuple slices, and values assigned from Any.
• Dataclass fields backed by descriptors are now checked for incompatible read and write types under the new bad-dataclass-descriptor error kind.
• String targets passed to unittest.mock.patch are validated, with nonexistent attributes reported as missing-attribute-patch-target warnings.
• Literal regular expressions are checked for invalid patterns and capturing groups under the new regex error kind.
• Django support now understands reverse ForeignKey, OneToOneField, and ManyToManyField relationships in the same file, while Django REST Framework serializers avoid false override errors for common Meta and field patterns.
• SQLAlchemy update().values() checks values against mapped model fields.
• PyTorch modules recognize attributes registered through register_buffer and register_parameter.

Language Server

• Workspace symbol search now includes methods, nested classes, nested functions, and class attributes.
• Cross-file call hierarchy, type hierarchy, and find-references now work without first opening every relevant file.
• A new change-signature refactoring updates a function's parameters and its call sites together.
• New quick fixes remove unused imports and insert assert x is not None when an optional value needs narrowing.
• Inlay hints can add required imports, are clickable for navigation, and now handle callable objects, instance methods, positional arguments, and **kwargs: Unpack[TypedDict] more accurately.
• Rename and navigation are more reliable for relative imports, decorated functions, named dataclass and Pydantic arguments, operators, module paths in strings, and legacy type-parameter declarations.
• Custom pyrefly.lspPath values now work correctly with Windows, home-relative, and workspace-relative paths.
• LSP clients can provide extraSearchPaths and extraProjectExcludes during initialization, improving integration with editors that manage their own import paths and excluded directories.
• Editors can display custom build-system activity and failures through the new pyrefly/typeErrorDisplayStatusChanged notification.

Performance

• TSP now reuses analysis for unopened files instead of solving the same module for every request. In a captured Pylance session, 22,294 unopened-file getComputedType requests fell from 668 seconds to 3.4 seconds, while total request time fell from 671 seconds to 6.4 seconds.
• Unknown-name suggestions are dramatically faster in files with very large scopes. Pyrefly now skips suggestion work for diagnostics that will be discarded and rejects unlikely candidates before computing their full edit distance. A pathological internal case fell from 96.8 seconds to 0.62 seconds, while focused benchmarks improved by 15–1,390x.

Configuration & CLI

• # type: ignore[pyrefly:<code>] comments suppress only the named Pyrefly diagnostic without hiding unrelated errors on the same line.
• The new type-ignore-unknown-tag-behavior option controls how tags belonging to other tools affect Pyrefly diagnostics: they can have no effect, downgrade diagnostics to warnings, or retain the legacy blanket-suppression behavior.
• The new replace-untyped-imports-with-any option replaces selected installed third-party packages with Any when they provide neither stubs nor a py.typed marker.
• pyrefly init automatically translates mypy's global and per-module follow_untyped_imports settings to the new option.
• baseline-matching-mode can match diagnostics by their column or concise description, reducing churn when unrelated code moves.
• baseline-format can write full metadata or a minimal representation containing only the fields needed for matching.
• baseline-error-level can expose matched diagnostics at info, warn, or error severity instead of hiding them, with baseline provenance included in text, JSON, SARIF, and summary output.
• --prune-baseline removes stale entries without recording new errors, while --error-stale-baseline lets CI reject a baseline containing obsolete entries.
• The opt-in treat-all-caps-as-final option treats reassignment of ALL_CAPS names as a bad-assignment.
• Projects can require a compatible Pyrefly version from pyrefly.toml using a PEP 440 version constraint.
• The new python-interpreter-find-command setting supports custom interpreter discovery.
• Multiple --output destinations with different formats can be specified in one CLI invocation.
• New documentation explains how to integrate Pyrefly with Pants through the pants-pyrefly plugin.

Experimental Extensions

• A composable type-level DSL now describes tensor shape transformations, and the JAX, NumPy, and PyTorch stubs have migrated from the decorator-based V1 shape system to direct V2 signatures.
• Shape-aware JAX stubs now cover array creation, indexing, reductions, searching and sorting, FFT, linear algebra, einsum and other contractions, and most of jax.lax.
• The new pyrefly-numpy-stubs package brings shape-aware checking to NumPy alongside the existing PyTorch support.
• The legacy @shaped_array API has been removed; custom shape annotations must migrate to IntTuple-generic classes and the V2 DSL.
• Polars DataFrame analysis now tracks schemas through construction, select, with_columns, group_by().agg(), joins, CSV readers, and lazy/eager conversion, with typed Series, nested and owned dtypes, and schema information from variables, calls, and TypedDicts.
• PEP 593 Annotated[DataFrame, Schema(...)] supports exact and open schema contracts, while the new column-schema-mismatch and duplicate-column errors catch invalid schemas and conflicting output columns before runtime.
• pandas DataFrames built with columns= now project their inferred schema onto the requested column set and order.

🐛 Bug fixes

We closed 88 bug issues this release 👏

• #3653: Eliminated exponential work when nested calls contain container literals by inferring shared expression subtrees once.
• #4678: Fixed pathological check times exceeding a thousand seconds on small files containing very long non-ASCII lines.
• #4437: Fixed a stack overflow crash when checking code with a recursive __new__ method. Pyrefly now detects direct recursive __new__ targets.
• #4459: Fixed a panic when a NamedTuple was defined inline inside a match statement. A dedicated MatchSubject binding key now prevents collisions.
• #4130: Star imports from py.typed packages installed in site-packages now recognize the package's public names as re-exports.

Thank you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.3.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@shobhitmehro, @rchen152, @asukaminato0721, generatedunixname2066905484085733, @yangdanny97, @grievejia, @kinto0, generatedunixname949130641157030, @lyydsheep, @ndmitchell, @stroxler, generatedunixname89002005232357, @connernilsen, @jcarreiro, @patrickswedish, @randolf-scholz, @vincevannoort, @renz011tzar, @ak4-sh, @tobyh-canva, @KotlinIsland, @Sanjays2402, @alexander-beedie, David Tolnay, @javabster, @samwgoldman, @IBlackVoid, @nitishagar, @WilliamK112, @NathanTempest, @ytausch, @xaskii, generatedunixname1431085361989520, @a7or, @markselby9, @heejaechang, Willem Kokke, @dillydill123, @kakolla, generatedunixname1699489071355949, @ting-hong-shieh, @kavix, @Vishwaspatel2401, @danielgaskins, generatedunixname89002005307016, @fangyi-zhou, @MarcoGorelli, @thomaspolasek, @tague, @paranoa233, @d34db3ff, @AMR5210, @DarkNightForge, @ternaus, @austin3dickey, @cakeni, @lolpack, @jakevdp, @Pager-dot, @tkim602, @anishfyi, @mangeshraut712, @jorenham, @Pyxelate, @DetachHead, @kavyansh18, @rootkiller6788, @auscompgeek, Khan Mohammed, @KSAGlory, @devteamaegis

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: September 03, 2026

About dev releases
Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.3.0-dev.4 bundles 198 commits from 23 contributors.

✨ New & Improved

Type Checking

• New composable type system primitives have been introduced for tensor shape types. See https://github.com/facebook/pyrefly/discussions/4807 for details.
• Overload selection now infers the most general return type assignable to all candidate return types when argument types are gradual.

Language Server

• Parameter-name inlay hints now align correctly for instance methods, skipping self and displaying hints for all user-visible parameters.
• Incoming call hierarchy and find-references now preserve parameter references in unopened files by escalating only the necessary modules to full analysis.
• Semantic autocomplete now works correctly on lines preceding comments by handling CRLF-aware comment offsets.
• Go-to-definition for decorated functions now navigates to the original function definition instead of the decorator's __call__ method.
• Workspace symbol search now includes class methods from project-indexed files, not just top-level exports.

Tensor Shape Support

• JAX, NumPy, and Torch stubs have migrated from the V1 shape DSL to type-level V2 signatures, removing decorator-based evaluation in favor of direct DSL calls.

Configuration

• The replace-untyped-imports-with-any flag and config option now replace imports from third-party packages missing stubs or py.typed markers with Any, matching mypy's follow_untyped_imports behavior.
• Mypy's follow_untyped_imports setting is now auto-migrated to the new replace-untyped-imports-with-any option.

🐛 Bug fixes

We closed 15 bug issues this release 👏

• #4552: Fixed an issue where semantic autocomplete failed on lines immediately above comments due to incorrect CRLF-aware offset calculations.
• #4484: Stopped reporting __tracebackhide__ as an unused variable, since pytest reads it implicitly when formatting tracebacks.
• #4611: Fixed parameter-name inlay hints being shifted by one position for instance-method calls, now correctly skipping self and aligning hints with actual parameters.
• #4616: Allowed plain subclasses of slotted dataclasses to assign new attributes without triggering false missing-attribute errors, since slot enforcement no longer applies to subclasses that don't declare slots themselves.
• #4626: Fixed bounded type[T] calls with custom metaclass returns to only substitute the constructor result with T when the inferred return is compatible with the bounded class, preserving unrelated metaclass __call__ return types.
• #3265: Fixed iter([0]) to infer Iterator[int] instead of Iterator[Any] by no longer using the generic Any bound from iter's signature to infer list element types.
• #4563: Made unresolvable __all__ state sticky across later mutations, so append, extend, and remove calls preserve DunderAllKind::Unresolvable and star imports continue using fallback behavior.
• #3569: Improved decorator error messages to detect when a decorated function is missing an injected parameter and report a clearer message instead of a confusing callable type mismatch.
• #1493: Fixed confusing override errors when overriding an overloaded method by improving error messages to show all overload signatures instead of suggesting conflicting parameter names.
• #4686: Fixed type(protocol_value) to produce type[Protocol] representing the unknown concrete runtime implementation, preventing false invalid-argument errors when used with isinstance.
• And more! #4676, #4684, #263, #3812, #3993

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.3.0-dev.4

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@stroxler, @rchen152, @samwgoldman, @grievejia, @jakevdp, @asukaminato0721, @kinto0, David Tolnay, @connernilsen, @ndmitchell, @DarkNightForge, @cakeni, @nitishagar, @shobhitmehro, @Pager-dot, @tkim602, @NathanTempest, @anishfyi, @mangeshraut712, @jorenham, @alexander-beedie, @Pyxelate, @yangdanny97

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: August 27, 2026

About dev releases
Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.3.0-dev.3 bundles 285 commits from 33 contributors.

✨ New & Improved

Type Checking

• Bound methods now display without their receiver parameter, so a diagnostic no longer reads as (self: A) -> None is not assignable to (self: A) -> None when the two sides genuinely differ.
• Bound methods are parenthesized when displayed inside a union, so (int) -> str | None is no longer ambiguous.
• Assigning a value of type Any to a variable with a declared type no longer erases the annotation, so later checks on that variable keep working.
• Wide Literal type hints are no longer discarded when solving generic calls, fixing false errors on Literal unions with more than four members.
• An attribute confirmed present by hasattr can now be deleted with del, and the narrowing is cleared afterwards so later reads correctly error again.
• Illegal shadowing of a legacy TypeVar by a same-named type parameter in an enclosing scope is now detected and reported.
• match statements on tuple subjects now narrow to Never for exhaustiveness, so assert_never works on multi-subject matches.
• Exhaustiveness checking for all match statements is now available as an opt-in.
• Descriptor __get__ is now applied when the attribute type is a union, rather than only for a single class.
• assert callable(x) now narrows to a callable returning Any instead of object, matching what the assertion is usually meant to express.
• Lambda parameter types are now inferred from the iterable passed to map(), so map(lambda foo: ..., items) is type checked.
• A value annotated as TypeForm can no longer be used as a type annotation, matching mypy, pyright, and ty.
• Unpacking **kwargs in a class header is now supported, with the unpacked fields validated against the class keywords.
• Calls that forward *args and **kwargs alongside known positional and keyword parameters are now checked against the keys the mapping actually provides.
• An unpacked TypeVarTuple in a callable parameter now accounts for optional arguments, so passing only the required ones checks.
• enum.Flag unions now match typing.Self in methods and classmethods, so combining members with | and returning Self checks.
• A forward reference to a nested class now resolves from annotations earlier in the enclosing class body.
• Reverse slices ([::-1]) of a fixed-length tuple now preserve the arity and the positional element types.
• Importing a re-exported @deprecated class or function now produces a deprecation warning at the import site, not just at the original definition.
• __all__.remove(...) is now taken into account when determining explicit exports, so removed names are no longer importable without an implicit-reexport error.
• Inferred return types that are callables are no longer truncated, preserving complex signatures.
• .so and .dll modules are now findable and treated as Any rather than failing to resolve.
• Equality narrowing on positive branches is now equality-aware, improving the types inferred after an == comparison.
• Literal regular expressions are now checked for unbalanced patterns and capturing groups, under a new regex error kind.
• Several stack overflows on recursive definitions are fixed: a recursive Self __call__, a recursive TypedDict, a recursive type alias used in a subscript, and protocol member lookup reached through __getattr__.

Language Server

• A new change_signature refactoring lets you edit a function's parameters and have call sites updated for you.
• A new "remove unused import" quick fix cleans up unused imports, including inside nested blocks, and leaves a pass behind where an import cannot simply be deleted.
• A new quick fix inserts assert x is not None for an optional value, so you can narrow it without writing the assertion yourself.
• Renaming a legacy TypeVar or ParamSpec now also updates the string name argument in its constructor call.
• Hover no longer expands type aliases, so you see the alias you wrote rather than its full expansion.
• Hover now shows the package a symbol comes from, and aligns the type and default value at the : or =.
• Hovering over not now highlights the full unary expression instead of just the operator.
• Go-to-definition and hover on an operator no longer include the left-hand side of the expression.
• Autocomplete now works for discriminated unions, including dict literals in call arguments, returns, and nested TypedDict fields.
• Go-to-type-definition on a function call now targets the function's own definition rather than the definitions of each parameter and return type.
• Go-to-definition on a named argument in a dataclass or Pydantic __init__ call now jumps to the specific field.
• Go-to-definition now resolves module paths written inside strings, such as "accounts.urls".
• Call hierarchy now finds cross-file callers without requiring the calling file to have been opened first.
• Type hierarchy now reports subtypes declared in other modules, not just those in the file being queried.
• Auto-import completions now work on the first request after a reload, instead of only appearing once an import has been typed.
• Notebooks that are not .ipynb files on disk now get language server features too.
• A relative binary path in the pyrefly.lspPath VS Code setting is now resolved against the workspace root rather than the extension's working directory.

Framework & Library Support

• Django REST Framework serializers no longer produce false bad-override errors for the inner Meta class pattern or for declared fields named like Field attributes.
• SQLAlchemy update() values are now checked against the mapped fields of the model, and SQL expressions are accepted in a values() call.
• SQLModel constructors now offer better hover text and completions.
• Polars support gained recursive and nested dtypes, plus owned dtype handling.
• Pydantic Field() defaults now infer correctly against wide Literal annotations.
• Attributes registered with self.register_buffer(...) and self.register_parameter(...) in a torch.nn.Module subclass are now recognized instead of reported as missing.

CLI & Configuration

• A new python-interpreter-find-command setting lets you supply your own command for discovering the Python interpreter.
• pyrefly.toml can now enforce a required Pyrefly version at runtime, using PEP 440 constraints.
• Snippets can now be read from stdin.
• Virtual environment discovery no longer treats a project directory containing a pyvenv.cfg as the virtual environment itself; project discovery looks for conventional .venv, venv, and env children instead.
• A package installed in site-packages no longer shadows Pyrefly's bundled stubs, which previously produced conflicting definitions of the same type.
• pyrefly init no longer emits redundant ignore-missing-imports entries alongside a global * wildcard when migrating a mypy configuration.
• Incomplete from import statements are now ignored rather than panicking.

Tensor Shapes

• We are building out a new DSL for describing shape transformations as type-level functions, and migrating the existing shape rules onto it. This work is ongoing.
• A new pyrefly-numpy-stubs package provides shape-aware NumPy stubs, alongside the existing pyrefly-torch-stubs.

🐛 Bug fixes

We closed 28 bug issues this release 👏

• #4585: Fixed a regression introduced in 1.3.0.dev1 where a module-qualified legacy TypeVar used as a type argument in a class base list produced a false invalid-type-var error saying the type variable was not in scope.
• #4678: Fixed pathological check times — over a thousand seconds on a small script — caused by repeatedly rescanning very long non-ASCII lines while collecting string ranges.
• #4569: Fixed an issue where Literal types with more than four members lost type inference, producing false errors on Pydantic Field() defaults and on any generic call given a wide Literal hint.
• #4187: Fixed an issue where narrowing of TypeVar-typed keyword arguments depended on the order the arguments were written in, so the same call could check or fail depending on argument order.
• #4557: Fixed a false positive bad-override when a subclass assigned a matching function to a callable ClassVar inherited from its parent.
• #4657: Fixed enum.Flag methods that combine members with | and return typing.Self being reported as returning the wrong type.
• #4595: Fixed false bad-override errors on Django REST Framework's ModelSerializer.Meta pattern, which is a configuration class rather than a true inheritance override.
• #911: Fixed assert callable(x) narrowing too aggressively: calling the narrowed value now yields Any rather than object.
• #3636: Fixed call hierarchy returning no incoming calls for cross-file call sites unless the calling file had already been opened in the editor.
• #4410: Fixed a forward reference to a nested class failing to resolve when used by an earlier annotation in the same enclosing class.
• And more! #4246, #4066, #4507, #4519, #4473, #3810, #438, #4576, #756, #4560, #4108, #3933, #4517, #4564, #3958, #3375, #1269, #1517

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.3.0-dev.3

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@stroxler, @samwgoldman, @rchen152, @asukaminato0721, @grievejia, David Tolnay, @shobhitmehro, @connernilsen, generatedunixname1699489071355949, @ting-hong-shieh, @kavix, @WilliamK112, @lyydsheep, @Vishwaspatel2401, @ndmitchell, @markselby9, @danielgaskins, @kinto0, @NathanTempest, generatedunixname89002005307016, @fangyi-zhou, @javabster, @MarcoGorelli, @thomaspolasek, @tague, @paranoa233, @d34db3ff, @AMR5210, @DarkNightForge, @ternaus, @austin3dickey, @cakeni, @lolpack

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: August 17, 2026

About dev releases
Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.3.0-dev.2 bundles 126 commits from 29 contributors.

✨ New & Improved

Type Checking

• Protocol methods named __call__ are now checked for override consistency like any other method, catching incompatible signatures that would fail at runtime.
• Scoped type aliases can now match TypeForm, fixing cases where valid type expressions were incorrectly rejected.
• no-any-return no longer fires on functions declared to return object, since all runtime values satisfy object.
• Non-callable __init_subclass__ attributes are now detected, catching runtime errors when a class inherits from a parent with a non-callable __init_subclass__.
• Type parameter defaults now correctly fall back to the appropriate type (object for TypeVars, tuple[()] for TypeVarTuples, ... for ParamSpecs) rather than always using Any.
• Unmatched type parameters at the end of a type parameter list now take into account previously added defaults when computing their own default values.

Language Server

• Diagnostics for untitled files now appear as squiggles in the editor, not just in the Problems panel.
• The language server now restarts atomically when configuration changes, preventing race conditions where file watcher updates could arrive while the client was down.
• Relative imports are now correctly updated when renaming files within a package, and imports are converted to absolute paths when a file is moved outside its package.

CLI & Configuration

• The Bazel integration is now documented, with setup instructions for the Bzlmod toolchain and aspect workflow.
• Mypy and Pyright configuration migration now preserves more settings, including strict mode, platform, untyped-body behavior, and follow_imports, with warnings when error codes cannot be mapped.
• Configuration documentation has been updated to reflect the preset=auto default behavior.
• Multiple --output destinations with different formats can now be specified on the command line, enabling simultaneous output to multiple formats.

Baseline Files

• Baseline files now omit line numbers and store only concise descriptions, reducing churn when unrelated code shifts and shrinking baseline file size.
• New --error-unused flag exits non-zero when the baseline contains unused entries, ensuring CI fails until the baseline is refreshed.
• New --remove-unused flag rewrites the baseline with only entries that still match, allowing the set of suppressed errors to shrink without recording new ones.
• Baselined errors can now be shown in output at a reduced severity using the baseline-error-level configuration option, with provenance markers indicating which results matched the baseline.

🐛 Bug fixes

We closed 16 bug issues this release 👏

• #4411: Annotation-only class attributes in stub files are now resolvable within the same class body, fixing cases where x: int followed by y = x incorrectly reported that x could not be found.
• #4342: datetime.datetime is now correctly recognized as a subtype of datetime.date, fixing false positives when dates and datetimes were used interchangeably.
• #4482: Functions with *args: *tuple[*Ts, Suffix] annotations now correctly track the variadic tuple shape during call matching, accepting arguments that match the prefix, middle, and suffix elements.
• #4471: Descriptor semantics are no longer incorrectly applied to annotated instance attributes that are initialized in __init__, fixing false errors when an annotation's type implements __get__ but no class-level descriptor exists.
• #4493: Scoped type aliases that resolve to Literal types can now match TypeForm, fixing cases where valid type expressions were rejected.
• #4055: Relative imports are now correctly adjusted when renaming files within a package, and converted to absolute imports when a file is moved outside its package.
• #4497: Diagnostics for untitled files are now published on the correct URI, so squiggles appear in the editor rather than only in the Problems panel.
• #4424: Explicit re-exports in __all__ are now preserved even when a later dynamic append or extend cannot be resolved, fixing false implicit-reexport errors for names like torch.Tensor.
• #4541: Field specifiers for descriptor-typed fields now correctly preserve init=False and required/optional status, fixing false errors when dataclass-transform field specifiers return descriptors.
• #4378: Variadic positional parameter hints now preserve the * marker, so args= becomes *args= in signature help.
• And more! #3987, #4401, #3706, #3447, #4521, #3183

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.3.0-dev.2

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@rchen152, generatedunixname2066905484085733, @yangdanny97, David Tolnay, generatedunixname949130641157030, @javabster, @shobhitmehro, @asukaminato0721, @samwgoldman, @kinto0, @alexander-beedie, @grievejia, @connernilsen, @tobyh-canva, @IBlackVoid, @nitishagar, @WilliamK112, @lyydsheep, @NathanTempest, @ytausch, @patrickswedish, @xaskii, generatedunixname1431085361989520, @a7or, @markselby9, @heejaechang, Willem Kokke, @dillydill123, @kakolla

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: August 06, 2026

About dev releases Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.3.0-dev.1 bundles 162 commits from 23 contributors.

✨ New & Improved

Type Checking

• You can now use Protocol as an instance of _ProtocolMeta in type checks, and Pyrefly correctly models Protocol using typeshed's _ProtocolMeta, making it assignable to ABCMeta.
• Classes that inherit from Sequence or other abstract base classes now correctly report when abstract methods remain unimplemented, even when the class doesn't directly extend ABC.
• Attribute access on type[type[X]] now uses the metaclass for more precise results instead of triggering internal errors.
• TypeVars explicitly bounded by Any now preserve dynamic attribute access instead of converting to object, fixing false missing-attribute errors.
• Legacy TypeVars declared in an enclosing class are now correctly flagged as out-of-scope when referenced inside nested classes, and type aliases that capture enclosing-scope TypeVars are also flagged.
• Out-of-scope legacy TypeVars in subscripted generics (e.g., list[T]() where T is unbound) now emit errors at the call site.
• Metaclass conflict detection is now more lenient, choosing a legal metaclass when multiple are available through inheritance, and redundant metaclass=type declarations are now allowed.

Language Server

• Inlay hints now include the imports they depend on, so accepting a type hint also inserts the necessary import statements automatically.
• Type annotations inserted from inlay hints now render Unknown as typing.Any to produce valid Python source.
• Inlay hints use from foo import X style imports by default when possible, falling back to import foo only when the module is already imported that way.
• Hover on a case _ wildcard now resolves to the match subject expression's type, not just the first token of the subject.
• Method-name completion no longer returns duplicate entries while defining methods.
• Positional inlay hints now display correctly even after keyword arguments.
• Keyword completion now works for **kwargs: Unpack[TypedDict] parameters, exposing each TypedDict field as a completable keyword argument.
• Completion suggestions now filter out TypedDict keys that aren't valid Python identifiers or are reserved keywords.
• Parameter-name hints now appear for callable instances by coercing them to their bound __call__ signature.
• Bare generic classes now preserve class-scoped type parameters when converting __new__ to a callable, fixing constructor argument inference.
• Inlay hints are now clickable, allowing you to navigate to class and type definitions directly from hint overlays.

Polars and pandas DataFrame Support

• df.with_columns(...) now infers each added or overwritten column's dtype from its Polars expression instead of leaving it Unknown.
• df.select(...) produces a precise column schema when its arguments are Polars expressions, not only plain column-name strings.
• df.group_by(...).agg(...) calls now infer a precise column schema, including grouping keys and aggregation outputs.
• pl.Series("a", [1]) now reveals Series[Int64] instead of the opaque Series class, carrying element dtypes forward.
• df.get_column(name) and df.to_series(index) now return typed Series[dtype] instead of an opaque Series.
• Polars DataFrames built with a schema= whose column set doesn't match the data now report a clear column-schema-mismatch error.
• Column names, element dtypes, construction flags, and join strategies are now resolved from their inferred types (e.g., Final or Literal[str]) instead of requiring bare literals.
• DataFrame columns built from variables or call results now infer their dtype from the value's type, not just from literals.
• DataFrames built from a TypedDict-typed value now infer columns from the TypedDict fields.
• df.lazy() and df.collect() now preserve the column schema across the conversion.
• pl.DataFrame[Schema] annotations now read the schema class's columns, so annotated parameters carry their schema into the function body.
• pl.read_csv and pl.scan_csv with inline schema= dictionaries now infer complete CSV schemas, and reader options like projections and overrides are applied.
• df.fill_null now models integer and float widening according to Polars runtime behavior.
• df[[]] (empty list subscript) now preserves the original schema instead of producing an empty schema.
• Duplicate Polars output columns are now reported with a new duplicate-column error.
• pandas DataFrames built with columns= now project the data onto the given column set and order.
• Column inference never reports a false error on correct Polars or pandas code.

Django Support

Pyrefly now understands reverse relationships between Django models in the same file:

• Reverse managers are added to the target of each ForeignKey, with the default <source>_set attribute or a custom related_name.
• Reverse OneToOneField relationships expose the source model directly on the reverse side.
• Reverse ManyToManyField relationships add a manager with the correct model type.
• Django related_name placeholders (class and app-label) are filled in, and disabled or malformed names create no attribute.

Error Suppressions and Diagnostics

• dataclass_transform now rejects unsupported keyword parameters, as required by the typing specification.
• mock.patch string targets are now validated, reporting missing imports or attributes at the string literal location.
• Missing attributes from mock.patch targets are reported as warnings under a new missing-attribute-patch-target error kind.
• Unused-ignore diagnostics now underline the suppression comment's # character, ensuring a valid UTF-8 boundary even after multibyte characters.

CLI and Configuration

• You can now treat ALL_CAPS variables as Final by enabling the treat-all-caps-as-final configuration option, which reports reassignment errors.
• The --typeshed-path option now works correctly when checking typeshed's own stubs, deriving module names from <typeshed_path>/stdlib.

🐛 Bug fixes

We closed 14 bug issues this release 👏

• #4077: Fixed an issue where attributes available only through __getattr__ or __getattribute__ were incorrectly rejected in protocol subtyping. Pyrefly now allows these fallback methods to satisfy protocol members, with special handling for class objects and certain dunders.
• #4126: Method-name completion was combining dedicated class/magic-method candidates with ordinary value completions, causing existing methods to appear twice. Method definitions now stay on the dedicated completion paths.
• #2797: Classes inheriting from Sequence or other abstract base classes now correctly report unimplemented abstract methods, even when the class doesn't directly extend ABC.
• #4437: Fixed a stack overflow crash when checking code with a recursive __new__ method. Pyrefly now detects direct recursive __new__ targets.
• #4459: Fixed a panic (Key Anon already exists) when a NamedTuple was defined inline inside a match statement. A dedicated MatchSubject binding key now prevents collisions.
• #385: Pyrefly now checks whether a context manager suppresses exceptions when doing type narrowing, so a raise inside a context manager that returns True from __exit__ no longer incorrectly narrows the type.
• #4453: Fixed a panic when a class named classproperty or cached_classproperty had no type arguments. The match arm now checks for type arguments before unwrapping.
• #4317: Redundant boolean conditions (e.g., A and True) no longer introduce placeholder narrowing operations, preserving the original narrowing behavior.
• #4444: Fixed a panic when writing output reports for files containing multibyte characters followed by # type: ignore comments. Unused-ignore diagnostics now underline the ASCII # character.
• #4377: Callable instances now show parameter names in inlay hints by coercing them to their bound __call__ signature.
• #4379: @total_ordering now recognizes non-synthesized rich comparison methods inherited through the class MRO, fixing false positives when __lt__ is defined in a base class.
• #3653: Fixed exponential blowup for nested calls containing container literals. Nested expressions are now inferred to a Type once up front, collapsing shared subtrees.
• #4405: TypeVars explicitly bounded by Any now preserve dynamic attribute access instead of converting to object, fixing false missing-attribute errors.
• #4267: Bare generic classes now preserve class-scoped type parameters when converting __new__ to a callable, fixing constructor argument inference.

And more! #4430, #4417, #4387, #4315, #3678, #3334, #4380, #2313, #1130, #4388, #4386, #4390, #4399, #4443, #4455, #4457, #4464, #4447, #4436, #4441, #4442, #4451, #4452, #4456, #4458, #4460, #317, #1576, #4331, #4304, #4393, #4361

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.3.0-dev.1

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@shobhitmehro, @rchen152, @asukaminato0721, generatedunixname2066905484085733, @yangdanny97, @grievejia, @kinto0, generatedunixname949130641157030, @lyydsheep, @ndmitchell, @stroxler, generatedunixname89002005232357, @connernilsen, @jcarreiro, @patrickswedish, @randolf-scholz, @vincevannoort, @renz011tzar, @ak4-sh, @tobyh-canva, @KotlinIsland, @Sanjays2402, @alexander-beedie

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: September 16, 2026

Pyrefly v1.2.1 is a patch release with a single performance improvement.

⚡ Performance

• TSP requests on a file that is not open (for example getComputedType) used to solve the whole module from scratch in a throw-away transaction, then discard that work once the request finished. The solve is now committed to shared state when possible, so later requests for the same file reuse the earlier solve instead of repeating it. In a captured Pylance session with 43,811 getComputedType requests, median latency for non-open-file requests dropped from 16.9ms to 0.07ms, and total TSP request time for that session fell from about 671s to about 6.4s.

📦 Upgrade

pip install --upgrade pyrefly==1.2.1

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

Release date: July 31, 2026

Pyrefly v1.2.0 bundles 901 commits from 59 contributors.

✨ New & Improved

Type Checking

• Attrs classes are now fully supported with comprehensive field synthesis, validation, and special-method generation. Pyrefly recognizes @attr.s, @define, @frozen, and their variants, handling field specifiers (attr.ib(), field()), converters, validators, defaults, and private-field aliasing. Converters are typed from their real input type rather than Any, including the @<field>.converter decorator, attrs.converters.pipe, attrs.converters.default_if_none, and generic converters like copy.deepcopy. See the new attrs documentation for details.
• functools.partial is now type-checked instead of treated as opaque. Bound arguments are validated at construction and Pyrefly synthesizes a precise residual signature for the remaining parameters, so errors surface at both the partial(...) call and the later invocation. Generic functions, overloads, constructors, bound methods, and **Unpack[TypedDict] parameters are supported, and results expose .func, .args, and .keywords. Precise residual callable assignment is enabled by the strict and all presets or explicitly with strict-partial-subtyping.
• Functions decorated with functools.singledispatch now type-check calls using the signature of the function you decorated, and registered implementations are checked against that function's first parameter. Generic singledispatch functions infer from call arguments instead of reporting Unknown.
• Pyrefly can now warn when a function declared to return a concrete type returns Any, with separate diagnostics for explicit and inferred cases. Off by default, and migrated automatically from mypy's warn_return_any.
• Pattern matching is substantially more precise: positional class patterns resolve attribute names from __match_args__ at solve time, sequence element captures read from the narrowed subject so sibling constraints refine them, and isinstance on a facet filters the parent union to matching members. Fully covered class and sequence patterns now subtract their union member from later cases.
• Unpacking a variadic tuple with a fixed prefix and suffix no longer smears those elements into the starred capture, so a, *rest, b = t where t: tuple[int, *tuple[bool, ...], str] types rest as list[bool].
• TypedDict classes now synthesize __required_keys__ and __optional_keys__, so protocols requiring them (like those in langgraph) satisfy structural checks. .get() and .pop() with literal defaults preserve the field type.
• Overload handling improved throughout: constrained TypeVar arguments expand during resolution, rejected overloads no longer leak argument errors into diagnostics, and exact callback-forwarding signatures resolve overloaded callbacks against forwarded arguments for helpers like asyncio.to_thread.
• Enum .value on an enum type now infers as the union of member literal values instead of widening to the mixed-in data type.
• Lambda parameters are contextually typed more thoroughly. Types are stored directly rather than resolved through inference variables, and *args/**kwargs resolve from callable hints to tuple[...] and dict[str, ...] inside the body while preserving element types in the signature.
• All properties are now treated as data descriptors, and reflected binary-operation dunders are tried first for proper subclasses, fixing a class of incorrect attribute and operator results.
• Cyclic type aliases reachable from an annotation are now detected instead of hanging, and class finality is taken into account when deciding whether a condition is redundant.
• Continued basedpyright parity work: class instance truthiness is recognized, code under if TYPE_CHECKING is handled consistently, typing_extensions.sentinel is supported with relaxed naming restrictions, and super(cls, cls) is accepted.
• copy.replace is now type-checked like dataclass replacement, and isinstance(x, type) preserves type arguments when narrowing unions.
• Narrowing a receiver typed as Self to a subclass now preserves Self, eliminating false return errors in methods that return the narrowed receiver.

Library Support

• Pydantic constructor synthesis now honors populate_by_name and built-in alias_generator functions, ignores Field(init=False) to match runtime, and treats frozen as a readonly field reason.
• Django ForeignKey targets now resolve attribute expressions and string references such as "app_label.Model", preserving the generated relation and <field>_id types.
• Bare factory-boy factory calls now return the model type via FactoryMetaClass.
• PEP 561 partial stub packages are now supported in imports. Pyrefly reads the partial marker from py.typed and merges the stubs with the runtime package, deferring to the runtime package for omitted modules while preserving .pyi-before-.py precedence for provided ones.
• A configured typeshed-path now supplies stdlib stubs as well as third-party stubs, enabling complete custom-typeshed testing and overrides.

Language Server

• Hover now resolves keyword arguments, renders callable protocols as their __call__ signature, preserves overload docstrings at call sites, shows enum fields, wraps nested callable and Concatenate[...] signatures for readability, and covers and/or operators, augmented assignments, and union methods.
• Auto-import completions respect python.analysis.autoImportCompletions, rank deprecated stdlib typing aliases below their modern equivalents, avoid duplicates for already-imported modules, and preserve import aliases correctly.
• Rename now works on aliased imports and across files for keyword arguments, and renaming a Protocol class targets the class rather than __init__.
• Go-to-definition now navigates directly to symbols in non-Python files such as .thrift, including nested attribute and enum access and intermediate components of multi-dotted imports.
• Inlay hints debounce server-side (default 150ms), preventing width jitter while typing. NewType values now use their callable constructor signature instead of producing an invalid type[N] annotation.
• Notebook support improved: hover and type lookups work past the first cell, and inlay hints, document symbols, references, and diagnostic grouping work in cells following markdown cells.
• Document symbols fall back to flat SymbolInformation for clients such as Helix, semantic tokens cover with ... as and except ... as bindings, and cross-file diagnostics refresh on save in strict-spec clients such as Zed.
• #region/#endregion markers create folding regions, and selection ranges now follow AST nesting from expression to statement to scope to document.
• Baselined errors now appear as hints instead of errors, making it easier to distinguish new issues from known technical debt. Baselining also now applies correctly to unused-ignore diagnostics.
• Match captures receive consistent semantic highlighting and preserve their declaration identity for go-to-definition.
• lspArguments defaults to ["lsp"] when empty, preventing startup failures in dev containers and remote environments.
• The VSCode extension adds an "Infer Types for Current File" command to the command palette.

Error Reporting

• New opt-in diagnostics include implicit-bool, invalid-cast, invalid-abstract-method, unused-call-result, empty-body, missing-super-call, unsupported-dynamic-base, implicit-reexport, unknown-argument-type, unknown-attribute-type, unknown-variable-type, implicit-any-lambda, untyped-function-decorator, untyped-class-decorator, unused-type-ignore, and no-any-return.
• Dict literal element type errors now report on the exact line of the offending key or value, and missing-attribute errors gain a single-line header with the full type when more than one class lacks the attribute.
• Error summary output is sorted by count then name for stable ordering, and --output-format=min-text flattens multi-line headers so each error stays on one line.
• --output-format=code-climate produces GitLab-compatible Code Quality reports, while full-text-with-github combines readable diagnostics with GitHub workflow commands and is now used by the Pyrefly action.

Coverage

• pyrefly coverage is no longer marked experimental.
• A [coverage] config table with includes and excludes can target a file set different from the project globs, with --project-excludes and positional FILES... taking precedence over it.
• --public-only keeps public re-exports from excluded files, so a symbol is only excluded when all of its public re-export locations are. Privately named classes and their members are excluded unless exported via __all__.
• --fail-under always prints findings whether or not the threshold is met.
• Coverage runs stream results as modules are solved, substantially reducing peak memory and improving runtime on large projects.

Configuration & CLI

• pyrefly infer --dry-run previews inferred annotations without modifying files and exits unsuccessfully when changes would be made, making it suitable for CI.
• python-platform accepts one platform, multiple platforms, or all platforms. Platform guards are folded only when every configured platform agrees.
• File-level # pyrefly: ignore-errors[code] directives selectively suppress named error codes using the same parent-kind matching as line-level ignores.
• The suppress command's --remove-unused=type mode also removes unused # type: ignore comments.
• --update-baseline validates the baseline after config resolution, so a baseline configured in pyproject.toml works without repeating --baseline.
• Config migration surfaces a malformed [tool.mypy] section instead of silently falling back to pyright, and TOML parse errors point at the offending value rather than the start of the file.

Stubgen

• Explicit TypeAlias right-hand sides and static __all__ literals are now preserved, so re-exports survive in the stub.
• Implicit class variables are wrapped in ClassVar[...], and multi-line parenthesized expressions keep their parentheses, preventing IndentationError in generated stubs.
• Async generators are emitted as plain def with AsyncGenerator return annotations, following the typeshed convention.
• Callable-typed values with differing return types across overloads render as Callable[..., Incomplete] instead of bare Incomplete, and statements guarded by conditions other than TYPE_CHECKING are no longer dropped.

Bazel Integration

• A new, experimental bazel-check command adds Bazel-focused type-checking for projects that provide source information through JSON manifests. It is intended to collaborate with the new rules_pyrefly Bazel rule project.

Tensor Shape Types

• Many improvements. Still early alpha state.

Performance

• Caching working-directory resolution eliminates repeated process-global syscalls, with reported multithreaded speedups of up to roughly 35% across the benchmark corpus. Directory-entry caching is now enabled unconditionally, and repeated pkgutil namespace probes are cached during import resolution.
• Bundled typeshed archives are now split into independently versioned stdlib and third-party archives, reducing optimized stdlib construction from 20.45ms to 4.97ms and deferring third-party lookup until site-package resolution.
• Bundled stub paths are stored once using immutable load-map indices, reducing retained heap and improving optimized construction by about 4% for stdlib and 6% for third-party bundles.
• Interpreter discovery now validates candidates with the environment query directly and reuses its cached result, reducing empty auto-configured checks from 49.8ms to 35.3ms.
• Smaller calculation cells reduce memory by roughly 2-4% on tested repositories, while lock-free reads of computed answers improve wall and CPU time by roughly 2%.
• Diagnostics are more stable across repeated runs, fixing flaky error-count changes observed in projects such as SymPy and apprise.

⚠️ Behavior Changes

These may surface new errors or warnings in code that checked cleanly under v1.1.0.

• isinstance narrowing now consumes dynamic uncertainty before intersecting with the target type, so x: Any narrowed by isinstance(x, C) refines to C instead of preserving the Any. This closes a type-safety hole while sacrificing the gradual guarantee in exchange for more precise runtime-evidence-based narrowing.
• Unannotated class attributes are now inferred by unioning the types of all assignments in the constructor, instead of taking the type of the first assignment.
• A file-level # pyrefly: ignore-errors directive placed after code now emits a misplaced-ignore warning, directing users to move it into the file preamble or use a line-level suppression.
• direct-abstract-base-instantiation is now separated from bad-instantiation and is a warning by default.
• invalid-type-checking-constant is a new default error for user-defined TYPE_CHECKING constants that are not typed as bool.
• useless-overload-body is a new default warning for executable logic in @overload declarations, whose bodies are never executed at runtime.
• implicit-any-attribute now focuses on Any synthesized at an attribute assignment; propagated Any is reported separately as the off-by-default unknown-attribute-type, so per-code configurations may need updating.
• More runtime-invalid constructs are now rejected, including incorrect string-literal unpacking and builtin slices, invalid dataclass and NamedTuple forms, assignments to bound-method attributes, duplicate KW_ONLY markers, and invalid __init_subclass__ calls.
• Additional typing-spec checks now diagnose legacy TypeVars not assigned to their declared name, raw-string quoted types, defaults on self or cls, and super() in directly defined NamedTuple methods.

🐛 Bug fixes

We closed 137 bug issues this release 👏

• #3867: Fixed a 1.1.0 regression where isinstance() narrowing broke after an unrelated isinstance() check in a returning sibling branch, restoring correct narrowing behavior.
• #3893: Fixed a stack overflow when checking self-referential protocols with overloaded methods.
• #3841: Unpacking a TypeVar bounded by a heterogeneous tuple now preserves each positional element type instead of widening every element to their union.
• #3881: Fixed inherited kw_only=True handling for SQLAlchemy-style declarative bases, preventing false "field without default may not follow field with default" errors in subclasses.
• #1323: enumerate() over tuple literals now preserves element types, so for i, x in enumerate(("a", "b")) types x as Literal["a"] | Literal["b"].
• #3437: Fixed a stack overflow when checking recursive enum classes by removing the recursive Flag subtype check.
• #3354: Fixed a panic with fuzzed NamedTuple code by adding a distinct binding key for invalid assignment targets.
• #4071: Fixed an incorrect bad-override error when a child class generic over a TypeVarTuple overrides a parent method with the same *args: *Ts signature.
• #3561: Fixed a false positive unannotated-return for @no_type_check functions.
• #3900: Dataclass and Pydantic BaseModel fields named "self" are no longer incorrectly flagged on construction.
• And more! #3445, #3596, #3552, #2945, #3879, #3887, #3891, #2858, #3787, #3293, #3928, #3688, #3890, #3912, #3945, #3926, #3924, #3429, #3873, #3976, #3882, #897, #3585, #3584, #2689, #2346, #4024, #4025, #4019, #4020, #3345, #3321, #3989, #3998, #4021, #3730, #3732, #3997, #4062, #4083, #4018, #4023, #3949, #4022, #4093, #3974, #4073, #4094, #4035, #4109, #3619, #3240, #3305, #3638, #3546, #4107, #3329, #2495, #4034, #3435, #3701, #3154, #3085, #2817, #1510, #964, #1866, #3821, #3669, #3368, #1663, #907, #2257, #3595, #4155, #3742, #3888, #2132, #4170, #3731, #1621, #2851, #4247, #4228, #4163, #3365, #4255, #3238, #2942, #1583, #4060, #3805, #3883, #4177, #4193, #1819, #3422, #4165, #2474, #2932, #3745, #4072, #3668, #4305, #2517, #4192, #3658, #2574, #3911, #3897, #4319, #2287, #2965, #2503, #4307, #4325, #632, #3903, #4334, #4225, #3876, #4168, #4262, #3065, #2064, #4324, #4070

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.2.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@stroxler, @shobhitmehro, @yangdanny97, @asukaminato0721, @rchen152, @kinto0, @samwgoldman, @grievejia, @jorenham, @NathanTempest, @anushamukka-dev, @ericzhonghou, @connernilsen, @tobyh-canva, @aodihis, @nitishagar, @kz357, @WilliamK112, @mikeleppane, @markselby9, @goutamadwant, @brosenfeld, @alexander-beedie, @ak4-sh, @xaskii, @qnox, @QEDady, @oprypin, @MannXo, @javabster, @fangyi-zhou, @durvesh1992, @arthaud, @vivekjm, @VasuAgrawal, @teerthsharma, @SarahMKosowsky, @roian6, @Punisheroot, @paranoa233, @olekuhlmann, @ndmitchell, @magic-akari, @maggiemoss, @lesbass, @lennardwalter, @knQzx, @Kartikey077, @JakobDegen, @ibraheemshaikh5, @hrolfurgylfa, @fhoehle, @dillydill123, @DibbayajyotiRoy, @coclique, @arogozhnikov, David Tolnay, Myles Matz, pratved64

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: July 24, 2026

About dev releases Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.2.0-dev.3 bundles 250 commits from 29 contributors.

✨ New & Improved

Type Checking

• TypedDict classes now synthesize __required_keys__ and __optional_keys__ attributes during attribute lookup, so protocols requiring these attributes (like those in langgraph) work correctly.
• Attrs fields can now use the @<field>.converter decorator (added in attrs 26.2.0) to define converters, and the converter's input type is correctly used for the __init__ parameter.
• attrs.converters.pipe now types the __init__ parameter as the first converter's input type instead of Any, so invalid constructor arguments are caught.
• attrs.converters.default_if_none now types the __init__ parameter as <field type> | None instead of Any, matching the converter's runtime behavior.
• Generic function converters in attrs fields (like copy.deepcopy) now solve their type variables against the field's declared type, so the __init__ parameter is correctly typed.
• Bare generic class converters in attrs fields now infer their element type from the field annotation, so converter=tuple on a Sequence[int] field types the parameter as Iterable[int].
• Polars DataFrames constructed from dictionary literals now infer a schema tracking each column's name and type, so later column access is type-checked.
• Polars .select(), .drop(), .rename(), and .with_columns() operations now preserve and transform the DataFrame schema, keeping column information through method chains.
• Polars .filter(), .sort(), and .fill_null() operations now preserve the DataFrame schema unchanged, since they only affect rows.
• Pandas DataFrames are now tracked with partial schemas (marked with ... in display), so known columns are type-checked while avoiding false positives from dynamic column operations.
• functools.partial now type-checks bound arguments and synthesizes a precise residual signature for the remaining parameters, catching errors at construction and call sites.
• functools.partial over generic functions now preserves type variables, so bound arguments can solve them and the residual stays generic.
• functools.partial over overloaded functions now resolves to the matching overload branches, so later calls still benefit from overload resolution.
• functools.partial over class constructors and bound methods now works correctly, checking arguments and producing the expected instance type.
• functools.partial results now expose .func, .args, and .keywords attributes and narrow correctly in isinstance checks.
• functools.partial over **Unpack[TypedDict] splats now expands the TypedDict fields and checks the residual parameters correctly.
• Enum .value on an enum type (not a specific member) now infers as the union of member literal values instead of widening to the mixin type.
• Positional class patterns now narrow matched attributes correctly, resolving the attribute name from __match_args__ at solve time.
• Sequence pattern element captures now read from the narrowed subject type, so sibling element constraints refine the captured types.
• isinstance checks on facets (like tuple elements or union members) now filter the parent union to matching members.
• Unpacking variadic tuples with fixed prefix/suffix now types starred captures precisely instead of smearing the fixed elements into the star.

Language Server

• Misplaced file-level # pyrefly: ignore-errors directives (placed after code) now emit a misplaced-ignore warning pointing users to move them to the top.
• Module auto-import completions no longer suggest duplicate entries for modules already imported with regular import statements.
• Overloaded class methods now associate the implementation's docstring with the overload chain, so hover shows documentation at call sites.
• Import alias names (import x as y, from x import y as z) are now classified as definition contexts, so completions don't suggest module paths for them.
• Completions for import aliases now preserve the original exported name and generate correct from model import MyModel as MyModelAlias statements.
• Inlay hints now debounce server-side (default 150ms) to prevent width jitter while typing, settling only when editing pauses.
• Keyword-argument hover now resolves parameter types from the defining module and falls back to the selected call signature when refinement is unavailable.
• Hover on and/or operators now returns the enclosing boolean expression range for better context.
• Renaming a Protocol class now renames the class symbol instead of incorrectly renaming __init__.
• Selection ranges (textDocument/selectionRange) now follow AST nesting from expression to statement to scope to document, with support for #region/#endregion markers.
• #region/#endregion folding markers are now recognized (including nested regions and spaced # region), independently of comment-section folding.
• TSP type queries (getComputedType, getDeclaredType, getExpectedType) now resolve correctly for files that aren't open in the editor.
• Pyrefly client settings (pyrefly.*) are now ignored when running as a type server (TSP mode), so stale extension settings don't interfere with Pylance.

Error Reporting

• A new unknown-column error kind flags reads of DataFrame columns that don't exist in the known schema.
• A new column-type-mismatch error kind flags Polars column literals whose elements cannot share one dtype.
• A new implicit-reexport error kind (default: ignore) flags imports of names that are only available through plain import/from ... import (not explicit re-exports).
• A new invalid-type-checking-constant error kind flags user-defined TYPE_CHECKING constants that aren't assignable to bool.
• A new missing-super-call error kind (default: ignore) flags __init__, __new__, or __init_subclass__ methods that override a non-object parent without calling the parent method.
• A new empty-body error kind (default: ignore) flags ellipsis-only function bodies where None isn't assignable to the annotated return type.
• A new unused-call-result error kind (default: ignore) flags discarded function/method call results whose type is informative (not None, Any, or Never).
• A new invalid-abstract-method error kind (default: ignore) flags @abstractmethod decorators in non-abstract classes.
• Error summary output is now sorted by count then name, so ties break deterministically and the output is stable across runs.
• The full-text-with-github output format now emits readable diagnostics followed by GitHub workflow commands, so source locations remain visible in raw logs.

Tensor Shape Typing

• Many improvements. Still early alpha state.

Polars & Pandas Support

• Polars DataFrame construction from dictionary literals now infers a complete schema with column names and types.
• Polars column reads by string literal now error on unknown columns, catching typos before runtime.
• Polars list subscripts (like df[["a", "b"]]) now narrow the schema to the selected columns in the requested order.
• Polars .select() narrows the schema to the named columns in the order given.
• Polars .drop() narrows the schema by removing the named columns while preserving the original order.
• Polars .rename() relabels columns in the schema, handling swaps correctly and falling back on ambiguous cases.
• Polars .with_columns() adds or overwrites columns in the schema, appending new names and preserving untouched columns.
• Polars selector strings (like "*" and regex patterns) are now recognized, so .select("*") and .drop("^col.*$") fall back instead of erroring.
• Pandas DataFrames are tracked with partial schemas (kind: Pandas, completeness: Partial), so known columns are checked without false positives from dynamic operations.
• Polars column literals now type each column from its first element and error on incompatible mixes, matching Polars runtime behavior.

Configuration & Tooling

• pyrefly coverage check --public-only now keeps public re-exports from excluded files, so symbols are only excluded when all public re-export locations are excluded.
• pyrefly coverage commands now accept a [coverage] config table with includes and excludes that override project globs, so coverage can be measured on a different file set.
• pyrefly coverage check --fail-under now always prints findings regardless of whether the threshold is met, so users see what's missing even when passing.
• pyrefly coverage now excludes privately-named classes (like _Foo) unless exported via __all__, consistent with other symbol kinds.
• Config files without a [tool.pyrefly] section are now only considered root markers, so pyproject.toml files don't shadow parent configs unless they contain Pyrefly settings.
• TOML parse errors now point at the offending value instead of the start of the file, so users can find the mistake quickly.
• The --project-excludes flag now takes precedence over coverage.excludes, and positional FILES... args also override coverage globs.
• Module handles for files without a config now apply the fallback_search_path, so __unknown__ files count under --public-only.

🐛 Bug fixes

We closed 48 bug issues this release 👏

• #4071: Fixed incorrect bad-override error when a child class generic over a TypeVarTuple overrides a parent method with the same *args: *Ts signature.
• #3745: TypedDict classes now synthesize __required_keys__ and __optional_keys__ attributes, so protocols requiring these attributes (like those in langgraph) no longer fail structural checks.
• #4109: Module auto-import completions no longer suggest duplicate entries for modules already imported with regular import statements (like import json).
• #3619: Overloaded class methods now associate the implementation's docstring with the overload chain's first declaration, so hover shows documentation at call sites.
• #3437: Fixed stack overflow when checking recursive enum classes by removing the recursive Flag subtype check and moving Flag detection downstream.
• #3354: Fixed panic with fuzzed NamedTuple code by adding a distinct binding key for invalid assignment targets, preventing collisions with synthesized functional NamedTuple bindings.
• #3240: Constructor hover types are now resolved before rendering, preventing internal @NNN variables from leaking into tooltips.
• #1323: enumerate() over tuple literals now preserves element types instead of widening to a generic tuple, so for i, x in enumerate(("a", "b")) types x as Literal["a"] | Literal["b"].
• #3305: #region/#endregion folding markers are now recognized (including nested regions and spaced # region), independently of comment-section folding.
• #4155: Generic function converters in attrs fields (like copy.deepcopy) now solve their type variables against the field's declared type, so the __init__ parameter is correctly typed instead of leaking a bare TypeVar.
• And more! #4123, #4125, #4127, #4128, #3330, #3638, #3546, #4107, #3329, #2495, #4034, #4082, #3900, #3435, #3701, #3056, #633, #3857, #3814, #3154, #3085, #2817, #1770, #1689, #1510, #964, #1866, #1084, #4164, #3821, #3727, #3669, #3368, #2504, #2235, #1681, #1663, #1373

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.2.0-dev.3

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@stroxler, @shobhitmehro, generatedunixname2066905484085733, @yangdanny97, @asukaminato0721, @kinto0, @anushamukka-dev, @samwgoldman, @rchen152, @NathanTempest, @jorenham, @aodihis, @tobyh-canva, @brosenfeld, @nitishagar, @goutamadwant, @grievejia, @roian6, @paranoa233, @kz357, @teerthsharma, generatedunixname949130641157030, @coclique, @SarahMKosowsky, @markselby9, @oprypin, @knQzx, @alexander-beedie, @ak4-sh

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: July 10, 2026

About dev releases Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.2.0-dev.2 bundles 158 commits from 23 contributors.

✨ New & Improved

Type Checking

• Functions decorated with functools.singledispatch now type-check calls using the signature of the function you decorated, catching argument errors like f("bad") when that function expects int. Registered implementations are also checked against that function's first parameter, so their dispatch types must be compatible.
• Generic singledispatch functions now infer their generic types from call arguments instead of reporting Unknown.
• Pyrefly can now warn when a function declared to return a concrete type returns Any, with separate diagnostics for explicit and inferred Any returns. These warnings are off by default for backward compatibility; you can enable them explicitly, or let Pyrefly migrate the setting from mypy when warn_return_any is enabled.
• isinstance(x, type) now preserves type arguments when narrowing unions, so type[int] | str narrows to type[int] instead of bare type.
• Class decorators annotated as returning type[Any] now make the decorated class behave dynamically, matching decorators that can substantially change the class at runtime.
• Class methods can now access generic class attributes through cls, fixing false missing-attribute errors on abstract base classes.
• Membership checks with Any/unknown items now invoke the container's __contains__ method and return bool instead of Unknown.
• copy.replace is now type-checked like dataclass replacement, so Pyrefly validates immutable updates more accurately.

Language Server

• Hover tooltips for union methods now look at each union member, so x: A | B; x.foo() correctly shows foo as a method when both A.foo and B.foo are methods.
• Hovering over augmented assignment operators like += now shows the __iadd__ definition and type, or the right-hand side literal type when that is the best available information.
• Attribute hovers like c.x now show where the attribute's type was narrowed instead of unrelated first-use info.
• Hover and type lookups now work correctly in notebook cells after the first.
• Inlay hints, document symbols, references, and diagnostic grouping now work correctly in notebook code cells that follow markdown cells.
• Auto-import completions now respect the python.analysis.autoImportCompletions setting, skipping auto-imports when disabled.
• Value completions are now skipped when typing a keyword-argument name (e.g., func(foo=1, ba|)), and statement keywords like try/while are no longer offered in expression contexts.
• Deprecated stdlib typing aliases (e.g., typing.List) are now ranked below their collections.abc equivalents in auto-import completions.

Bazel Integration

• A new, experimental bazel-check command adds Bazel-focused type-checking for projects that provide source information through JSON manifests. It is intended to collaborate with an in-progress rules_pyrefly Bazel rule implementation.

Tensor Shape Types

• Shape-aware stubs can now express methods whose types follow another method on the same object. This lets nn.Module.__call__ type-check like the module's forward method.
• SizeTuple is now the public way to write shape parameters, with support for compact syntax like ndarray[[2, 3], dtype] and unpacking with *Elements[SizeTuple].
• Torch and NumPy shape stubs now use SizeTuple, making it easier to model APIs involving multiple tensors with different shapes.
• Symbolic shape variables now use SymVar, written as N: SymVar in PEP 695 syntax. Shape arithmetic is now limited to these symbolic shape variables.

🐛 Bug fixes

We closed 26 bug reports this release 👏

• #897: Fixed an issue where attribute narrowing with optional values failed to preserve the narrowed type across conditional branches, causing false positives when accessing attributes after a null check.
• #3585: Fixed isinstance(value, type) narrowing for type[int] | str unions, which previously collapsed to bare type instead of preserving type[int].
• #3584: Fixed isinstance(value, type) narrowing for TypeForm[object], which previously produced type & TypeForm[object] instead of the correct type[int] after an issubclass check.
• #2689: Fixed subsequent isinstance(cls, type) and issubclass(cls, upper_bound) checks erasing TypeVar information, so type[F] is preserved through assertion chains instead of widening to the bound.
• #3806: Added no-any-return error kinds to detect returning Any from functions declared to return concrete types, with explicit and implicit variants and support for migrating mypy's warn_return_any setting.
• #4024: Fixed pyrefly coverage check --strict incorrectly labeling fully-Any symbols (e.g., def f(x: Any) -> Any) as coverage-partial instead of coverage-missing.
• #4062: Fixed pytorch-efficiency-lints not recognizing Tensor in common stub layouts.
• #4083: Fixed tuple(xs) losing track of tuple length when xs is already a tuple, now preserving known shapes like tuple[int, int] instead of widening to tuple[int, ...].
• #4093: Fixed an internal error when accessing __class__.__setattr__ on a class object, caused by missing metaclass handling.
• #4073: Fixed unpacked TypeVarTuple arguments like tuple[int, *Ts] not being assignable to varargs type tuple[int, *Ts] due to an internal mismatch in how Pyrefly represented the tuple types.
• And more! #4025, #4019, #4020, #4021, #3730, #3732, #3997, #4018, #4023, #3949, #4022, #3920, #4092, #3078, #3960, #4064

Thank you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly, we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.2.0-dev.2

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@stroxler, @grievejia, @shobhitmehro, @asukaminato0721, @jorenham, @kinto0, @yangdanny97, David Tolnay, @ericzhonghou, @connernilsen, @qnox, @mikeleppane, @dillydill123, @arthaud, @alexander-beedie, @NathanTempest, @fhoehle, @WilliamK112, @xaskii, @durvesh1992, @lennardwalter, @kz357, @nitishagar

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: July 1, 2026

About dev releases Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.2.0-dev.1 bundles 235 commits from 38 contributors.

✨ New & Improved

Type Checking

• Attrs classes are now fully supported with comprehensive field synthesis, validation, and special-method generation. Pyrefly recognizes @attr.s, @define, @frozen, and their variants, handling field specifiers (attr.ib(), field()), converters, validators, defaults, and private-field aliasing. See the new attrs documentation for details.
• isinstance narrowing now consumes dynamic uncertainty before intersecting with the target type, so x: Any narrowed by isinstance(x, C) refines to C instead of preserving the Any. This closes a type-safety hole while sacrificing the gradual guarantee in exchange for more precise runtime-evidence-based narrowing.
• TypedDict .get() and .pop() methods with literal defaults now preserve the field type when the default is assignable to it, so .get("x", "b") on a Literal["a", "b"] field returns Literal["a", "b"] instead of Literal["a", "b"] | str.
• Unannotated class attributes are now inferred by unioning the types of all assignments in the constructor, instead of taking the type of the first assignment.

Language Server

• Baselined errors (stored in a separate baseline file) now appear as hints in the IDE instead of errors, making it easier to distinguish new issues from known technical debt.
• Document symbol search now works in editors like Helix that don't support hierarchical symbols, returning a flat SymbolInformation list with dotted container names.
• Semantic tokens are now emitted for names bound by with ... as and except ... as, so those variables are syntax-highlighted consistently with other local bindings.
• Go-to-definition on non-Python source files (e.g., .thrift) now navigates directly to the symbol definition via text search instead of the top of the file, and works for nested attribute/enum member access.
• The unused-type-ignore rule detects # type: ignore comments that suppress no errors, helping clean up stale suppressions (off by default; enable with unused-type-ignore = "error" in pyrefly.toml).
• Cross-file diagnostics now refresh on save in strict-spec LSP clients like Zed, which previously needed a language-server restart to pick up changes in imported files.

Stubgen

• Multi-line parenthesized annotations, values, and return types are now re-wrapped in (...) when emitted, preventing IndentationError in the generated stubs.
• Callable-typed values with differing return types across overloads are now rendered as Callable[..., Incomplete] instead of bare Incomplete, preserving callability information.
• Implicit class variables (bare assignments in a class body) are now annotated as ClassVar[...] in emitted stubs, correctly distinguishing them from instance attributes.
• __all__ is now preserved verbatim when it's a static list/tuple literal, so re-exports survive in the stub.
• Async generators are emitted as plain def with AsyncGenerator return annotations instead of async def, following the typeshed convention and fixing coroutine-vs-generator confusion.

Tensor Shape Types

• The pyrefly-shape-extensions and pyrefly-torch-stubs packages are now published to PyPI alongside Pyrefly releases, providing runtime helpers and shape-aware PyTorch stubs for tensor shape type checking.
• The shape DSL now supports D[N] or D(N) runtime wrappers for dimension expressions, allowing evaluated annotations to survive Python runtime while preserving symbolic arithmetic.
• assert_shape runtime helper validates tensor shapes at runtime, falling back to rank-only checks for symbolic shapes.

🐛 Bug fixes

We closed 20 bug issues this release 👏

• #3867: Fixed a regression where isinstance narrowing silently stopped working after a sibling branch in the same if/elif/else chain narrowed a different variable and terminated. The lazy-builtins optimization incorrectly lifted isinstance into the fork base, producing a degenerate Phi that resolved to Never and broke downstream narrowing.
• #3893: Fixed a stack overflow crash when checking self-referential protocols with overloaded methods whose self: annotations reference the protocol itself. A new per-thread cycle guard prevents infinite recursion during overload filtering.
• #3841: Unpacking a TypeVar bounded by a tuple (e.g., Z: tuple[str, int]) now preserves positional element types instead of collapsing to a union. u, v = x where x: Z now reveals u: str, v: int instead of u: int | str, v: int | str.
• #3787: TypedDict .get(key, "literal") on a non-required key now returns the field type when the literal default is assignable to it, instead of widening to field_type | str.
• #3561: Functions decorated with @no_type_check no longer emit unannotated-return diagnostics, since the decorator explicitly opts the function out of type checking.
• #3900: Dataclass and Pydantic BaseModel fields named "self" are no longer incorrectly flagged with bad-keyword-argument and bad-argument-type on construction. The instance receiver is now named __dataclass_self__ when a field named self exists.
• #3881: SQLAlchemy declarative base classes with kw_only=True now correctly apply the keyword-only constraint to subclass fields, fixing false "field without default may not follow field with default" errors.
• #2858: Match subjects without a real narrowing name (e.g., match f(x):) now carry direct fallthrough narrows across cases, and the final capture forwards to the already-evaluated subject narrowed by previous cases.
• #3445: Packages with a PEP 561 py.typed marker no longer trigger untyped-import recommendations, even when imported as submodules.
• #3954: The typings/ directory under the config root is now auto-discovered on the CLI path (not just in the IDE), fixing a divergence where CLI and IDE had different stub search paths for the same config.
• And more! #3879, #3891, #3293, #3928, #3688, #3890, #3912, #3945, #3926, #3924

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.2.0-dev.1

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@stroxler, @shobhitmehro, @yangdanny97, @jorenham, @grievejia, generatedunixname2066905484085733, @connernilsen, @asukaminato0721, @samwgoldman, generatedunixname949130641157030, @kinto0, @NathanTempest, @ericzhonghou, @rchen152, @javabster, @QEDady, @mikeleppane, @markselby9, @aodihis, @arthaud, @DibbayajyotiRoy, Myles Matz, @ndmitchell, David Tolnay, @Kartikey077, pratved64, @maggiemoss, @goutamadwant, @kz357, @nitishagar, @hrolfurgylfa, @olekuhlmann, @JakobDegen, @lesbass, @fangyi-zhou, @ibraheemshaikh5, @alexander-beedie, @xaskii

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: June 18, 2026

Pyrefly v1.1.1 is a patch release with a single bug fix.

🐛 Bug fixes

• #3867: Fixed a regression introduced in 1.1.0 where isinstance() narrowing of a union variable silently stopped working when an earlier sibling branch in the same if/elif/else chain narrowed a different variable with isinstance() and returned. The later narrowing left the union untouched, producing false missing-attribute errors on code that checked correctly in 1.0.0.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.1.1

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

Release date: June 17, 2026

Pyrefly v1.1.0 bundles 788 commits from 72 contributors.

✨ New & Improved

Type Checking

• Pyrefly now correctly narrows TypedDict types after isinstance(x, dict) checks, treating them as runtime dict instances while preserving field information in the positive branch.
• Type narrowing for bounded and constrained TypeVars has been significantly improved. isinstance checks now correctly narrow Self and bounded type variables via their disjoint-base representatives, and negative narrowing on bounded TypeVars no longer produces false positives.
• Constrained TypeVars are now preserved through method calls and binary operations, so T & int where T: (int, str) correctly returns T & int instead of losing the TypeVar.
• Classes decorated with @dataclass(slots=True) are now recognized as PEP 800 disjoint bases when they synthesize non-empty __slots__, enabling proper multiple-inheritance conflict detection and type narrowing.
• Pyrefly now detects when methods override parent class methods without using the @override decorator, and a new quick fix can automatically add the decorator for you.
• Variance inference now correctly skips receiver parameters (like self and cls) when determining class variance, fixing false invariance reports for container-like classes.

Performance

• File discovery now uses the ignore crate with parallel traversal, making initial indexing 2-3x faster and dramatically reducing wall-clock time for large projects.
• Completed calculation results are now stored outside the mutex, reducing lock contention and improving performance on large codebases like homeassistant-core and transformers.
• Implicit builtins are now lazily materialized on first use instead of eagerly adding hundreds of import bindings to every module, reducing memory usage by 5-13% and CPU time by 10-28%.
• Literal unions are now capped at 256 non-enum literals or 4096 enum members per kind to prevent exponential type growth, and overall union size is capped at 4096 members.
• Bytes literals larger than 1024 bytes are now widened to bytes to keep type representations bounded.
• Wide tuple unions (more than 8 variants) are now collapsed into unbounded tuple types to prevent performance hangs and out-of-memory errors during type checking.

Language Server

• Hover tooltips now work correctly on subscript expressions without spaces (e.g., c[0]), showing the __getitem__ signature instead of garbled output.
• Literal completions are now offered in expected-type contexts like annotated assignments, return statements, and attribute targets, not just call arguments.
• Dictionary key completions now work in empty subscripts (d[) and half-typed subscripts (d["), suggesting known keys from TypedDicts and narrowed facets.
• Go-to-definition on from X import Y statements now falls back to the module file when the imported name can't be resolved (e.g., for non-Python modules like .thrift files).
• Quick fixes now use the file's actual line ending (CRLF or LF) instead of hardcoded \n, preventing mixed line endings.
• Added support for legacy pkgutil-style namespace packages

Type Server Protocol (TSP)

• The TSP backend now emits resolvable typing classes and TypeVars instead of opaque builtins, so hovering over special forms like Literal, Final, and ParamSpec now shows the correct name instead of Unknown.
• Function types in TSP responses now carry specialized parameter and return types, enabling Pylance to display real types instead of Unknown.
• Pyrefly now emits the protocol-conformant lowercase unknown sentinel in TSP responses instead of uppercase Unknown.
• Expected-type queries now return the contextually expected type (e.g., the parameter type for a call argument) instead of the computed type, making the typeServer/getExpectedType request actually useful.

Error Reporting

• No-matching-overload errors now show only the parameters relevant to the arguments you passed, hiding irrelevant optional parameters to make signatures easier to read.
• Arity mismatch details and call errors are now included in no-matching-overload error messages, making it clearer why an overload didn't match.
• The None hint in error messages now only suggests narrowing when it makes sense (e.g., in conditionals) and only suggests adding | None when you control the type.
• Variance errors on overloaded methods now point to the offending overload instead of always pointing to the first one.

Configuration

• The tensor-shapes config option has been removed. Tensor shape support is now automatically derived from whether shape_extensions is resolvable for the module being checked.
• Pyrefly now understands $MYPY_CONFIG_FILE_DIR when migrating mypy configs, stripping it to produce portable relative paths.
• Glob patterns in config files now require / separators (not OS-specific separators) for cross-platform consistency.

🐛 Bug fixes

We closed 89 bug issues this release 👏

• #3671: Fixed a stack overflow crash when a descriptor's __get__ method is itself a descriptor. Pyrefly now detects this self-referential case and terminates instead of recursing indefinitely.
• #3712: Fixed a crash when instantiating a nested functional NamedTuple in constructor defaults. Pyrefly now calls ensure_expr on the default value to avoid panicking during binding.
• #3789: Fixed a panic ("a variable has leaked from one module to another") when opening sympy/core/expr.py in the LSP. The lambda parameter cache is now keyed by (ModuleName, ModulePath, LambdaParamId) to distinguish in-memory and on-disk module versions.
• #3749: Fixed a false positive incompatible-overload-residual error on functools.reduce(operator.*, ...). The overload resolves correctly; the spurious diagnostic has been removed.
• #3819: Fixed unsupported-operation errors when matching on overloads. Protocol conformance now filters overloads by self: type, so a timedelta receiver correctly selects the matching overload instead of erroneously picking the first one.
• #3751: Pyrefly now rejects @dataclass decorators on NamedTuple classes, matching CPython's runtime behavior which raises a TypeError.
• #3773: Optional imports like try: import a except ImportError: a = None are no longer reported as untyped by pyrefly coverage.
• #357: Runtime-evaluated annotations now report uninitialized forward names for Python < 3.14 unless from __future__ import annotations is active, matching CPython's behavior.
• #3624: pyrefly coverage report no longer includes definitions from if __name__ == "__main__" guards, as those aren't importable at runtime.
• #3387: Foo[Bar] under from __future__ import annotations now binds Bar as static type information when Foo is a known class, avoiding false "uninitialized" diagnostics.
• And more! #2798, #3188, #3385, #3208, #3237, #3378, #3413, #3455, #3392, #3299, #3446, #3448, #3396, #1492, #2451, #3431, #3210, #3381, #2547, #3147, #3524, #3506, #3519, #3343, #3505, #3369, #3344, #3400, #3394, #3221, #3514, #3520, #3544, #3458, #3593, #3548, #3576, #3292, #3526, #2869, #3228, #3578, #3568, #3410, #3602, #3300, #3356, #3607, #3612, #1496, #3623, #3059, #3598, #3536, #3066, #3418, #3235, #3673, #3541, #3169, #3075, #1838, #3550, #955, #2711, #498, #3113, #3197, #3215, #1592, #2002, #2082, #2199, #2553, #2693, #3220, #2751, #3743, #3790, #3708, #3703

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.1.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@rchen152, @grievejia, @kinto0, @yangdanny97, @jorenham, @samwgoldman, @connernilsen, @stroxler, @shobhitmehro, @asukaminato0721, @javabster, @NathanTempest, David Tolnay, @mikeleppane, @maggiemoss, @arthaud, Eric Hou, Gregory Carlin, @thatfunkymunki, @hrolfurgylfa, @nitishagar, @tobyh-canva, @vivekjm, @QEDady, @rchiodo, @mdbernard

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: June 10, 2026

About dev releases Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.1.0-dev.2 bundles 250 commits from 37 contributors.

✨ New & Improved

Type Checking

• Improved handling of defaults for function parameters annotated with type variables. Parameters like x: T = 0 now correctly validate their defaults against the type variable's constraints or bounds, and the default value is properly used when solving type variables in function calls.
• Enhanced type narrowing for constrained type variables. Operations like isinstance checks and binary operations now preserve the type variable while correctly narrowing to specific constraints, fixing several false positives and negatives.
• Improved handling of methods on type variables. When calling methods on a type variable (e.g., x.lower() where x: T with T constrained to bytes | str), the return type now correctly preserves the type variable when the method returns self's type.
• Better support for shaped arrays across libraries. The tensor shape machinery now works with any array class that opts in via shape_extensions.shaped_array, including numpy.ndarray and jax.Array, not just PyTorch tensors.
• Improved literal promotion and handling in function parameter defaults, making type inference more predictable when defaults include literal values.
• Fixed handling of binary operations and comparisons on constrained type variables, ensuring the type variable is preserved when appropriate rather than degrading to a union of constraints.

Language Server

• Literal value completions now work in more contexts. When assigning to an annotated variable, returning from a function, or setting an attribute with a Literal type, the editor now suggests the valid literal values.
• New TSP endpoint typeServer/getExpectedType returns the contextually expected type at a cursor position (e.g., the parameter type for a call argument, the declared type for an assignment), enabling richer IDE features.
• Improved "move module member" refactoring. When moving a symbol to another module, Pyrefly now rewrites consumer imports automatically, updating from source import foo to from target import foo across the codebase.
• New "move symbol to new file" refactoring creates a new file for a top-level symbol, moves the definition, and updates all consumer imports in one action.
• Enhanced pytest fixture support. Go-to-definition and find-references now work for pytest fixtures used as function parameters, navigating to the fixture definition.
• Better handling of non-Python modules in build systems. Go-to-definition on imports from .thrift files and other non-Python modules now navigates to the module file when the specific symbol can't be resolved.

Coverage Reporting

• New pyrefly coverage check command provides a user-friendly way to verify type coverage meets a threshold, with configurable output formats and fail-under percentage.
• Coverage reports now exclude symbols that can't be imported due to shadowed namespace packages, providing more accurate coverage metrics.
• Improved handling of stub re-exports. When a stub re-exports a class, the class's members are now correctly excluded from the coverage report to avoid inconsistent results.
• Coverage reports now respect __all__ in stubs more accurately, only treating imports as public re-exports when they appear in __all__ or use the as alias syntax.

Error Reporting

• Error output is now significantly faster (up to 75% reduction in printing time for large error counts) through optimized rendering and buffering.
• New --output-format junit-xml option emits JUnit XML test reports, making it easier to integrate Pyrefly into CI dashboards.
• Improved error messages for None-related type mismatches. When passing T | None where T is expected, the error now includes an actionable hint suggesting narrowing with is not None or widening the expected type.
• Better error messages for missing overload matches, now including details about arity mismatches and specific argument type errors.

🐛 Bug fixes

We closed 24 bug issues this release 👏

• #3554: Fixed false-positive unknown-name errors after short-circuit boolean operations. Code like if SOMETHING_DEFINITELY_FALSE and A: no longer reports A as unknown, since it's unreachable.
• #3300: Fixed unknown-name false positive when a name is introduced via a walrus operator in a decorator. Names defined with := in decorator expressions are now visible after the decorated definition.
• #1496, #3418, #3623: Fixed handling of defaults for function parameters with type variable annotations. Defaults like x: T = 0 are now validated correctly and used when solving type variables in calls.
• #3059: Fixed __getitem__ resolution on type variables with constraints. Subscripting a type variable bounded by TypedDict or other subscriptable types now works correctly instead of falling back to object.__getitem__.
• #3603: Fixed type narrowing for discriminated TypedDict unions when using membership tests. Expressions like event["ph"] in ("X", "C") now correctly narrow the union to matching members.
• #3079, #3082: Fixed false-positive key errors after key in dict checks. When a TypedDict key is tested with in, subsequent subscript access no longer reports the key as possibly absent.
• #3607: Fixed import resolution when using a config file. Bare imports like from bar import func that work at runtime now resolve correctly even when a pyrefly.toml is present, via the new enable-fallback-search-path option.
• #357: Fixed unquoted forward reference handling in Python ≤3.13. Runtime-evaluated annotations now correctly report uninitialized forward names unless from __future__ import annotations is active.
• #3536: Fixed invalid-variance error location for overloaded methods. The error now appears on the offending overload signature rather than always pointing to the first overload.
• #3671: Fixed stack overflow when a descriptor's __get__ is itself a descriptor. Self-referential descriptor patterns now terminate gracefully instead of crashing.
• And more! #3235, #3673, #3541, #3684, #3647, #3632, #3626, #3640, #3641, #3639, #3645, #3701, #3664, #3598

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here.

📦 Upgrade

pip install --upgrade pyrefly==1.1.0-dev.2

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. Run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation.

🖊️ Contributors this release

@rchen152, @stroxler, @kinto0, @yangdanny97, @connernilsen, @grievejia, @NathanTempest, @jorenham, @samwgoldman, @asukaminato0721, David Tolnay, @lolpack, @mikeleppane, @maggiemoss, @MarcoGorelli, @JakobDegen, @arthaud, Anqi Wu, @terror, @bigfootjon, @aahanaggarwal, @rchiodo, @magic-akari, @SamB, @nitishagar, @ndmitchell, @NarxPal, Gregory Carlin, @javabster, @thatfunkymunki, @shobhitmehro, @hrolfurgylfa

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Release date: May 27, 2026

> About dev releases > Dev releases (versions like X.Y.Z-dev.N) are non-stable snapshots cut periodically from trunk. They give early adopters a chance to try in-progress features and surface issues before the next stable release, but they don't carry the same stability or compatibility guarantees as a stable release — don't pin production projects to a dev version.

Pyrefly v1.1.0-dev.1 bundles 250 commits from 40 contributors.

---

## ✨ New & Improved

### Type Checking

• New incompatible-comparison diagnostic catches comparisons like int == str where operand types can't overlap.

• Classes whose metaclass extends ABCMeta are now correctly treated as abstract.

• Frozen dataclasses reject manual __setattr__/__delattr__ overrides.

• Annotation-only descriptor fields are recognized as descriptors — fixes false positives for SQLAlchemy Mapped and similar asymmetric descriptor types.

### Language Server

• Code actions can convert dict literals to TypedDict, dataclass, or Pydantic model — with automatic imports.

• Sphinx cross-references (`,,) in docstrings now render as clickable links in hover tooltips.

• Inlay hints for class attributes defined in__init__` without explicit annotations.

• Supports python.analysis.diagnosticMode, python.analysis.importFormat, and python.analysis.inlayHints settings — full interop with the Python VS Code ecosystem.

• Added support for legacy pkgutil-style namespace packages

### Error Reporting

• New explicit-any error kind (ignored by default) warns when Any appears in annotations or type alias bodies; includes migration support for mypy/pyright codebases.

• Diagnostic paths in baseline.json are now relative and always use forward slashes — fixes baseline matching when CI checkout paths differ from local dev environments and across OSes.

• The annotation-mismatch error kind has been removed (it was never emitted).

### Configuration

• New all preset enables every error kind at error severity — for codebases that want comprehensive checking. Available in both the CLI and the VS Code python.pyrefly.typeCheckingMode setting.

• New pytorch-efficiency-lints flag turns on PyTorch efficiency checks at warn severity: catches .item() GPU sync, redundant .to(device), deprecated .cuda(), and print(tensor).

### Tensor Shapes

• Tensor shape operations now live in user-space stubs (torch/_shapes.pyi) via the new @uses_shape_dsl decorator.

• DSL compile errors and shape-DSL type errors now emit proper diagnostics with precise source spans instead of panicking.

• Recursive @shape_dsl_function definitions and invalid call signatures are caught at compile time.

### Stubgen

• Stubgen now emits synthesized __init__ for dataclasses, preserving constructor signatures in generated stubs.

### Build & CI

• Pyrefly now compiles on stable Rust — no more nightly toolchain dependency. GitHub CI workflows updated to match.

• musllinux wheels are now built for Alpine and other musl-based distros.

• Conformance test sources updated from upstream python/typing.

---

## 🐛 Bug fixes

We closed 34 bug issues this release 👏

• #2798: Fixed false positive not-iterable error when iterating over a list stored in a dict that also contains non-iterable values. When a dict was built inside a loop with heterogeneous inner dicts (e.g., {"start": date, "tasks": []}), Pyrefly incorrectly inferred the inner dict's value type as date instead of date | list[...], causing spurious errors when accessing val["tasks"].

• #3188: Fixed error suppression for multi-line implicit string concatenations. When a # pyrefly: ignore comment appeared above a multi-line implicit string concatenation, only the first error was covered. Pyrefly now reparses the AST to respect ignore comments for the entirety of the construct.

• #3385: Fixed false positive missing-override-decorator when assigning to inherited properties. If a child class assigned to a property (with a setter) defined in a base class, Pyrefly incorrectly flagged it as an implicit override.

• #3208: Fixed stubgen missing instance variables defined in __init__. Classes in generated stubs were missing attributes if those attributes were not explicitly annotated at the class level. Stubgen now emits synthesized __init__ for dataclasses, preserving constructor signatures.

• #3237: Fixed cross-file references lost when CRLF/LF line endings differ. When files on disk used CRLF but the editor sent LF-normalized content via textDocument/didOpen, byte offsets diverged, causing exact byte-range comparisons to fail. Pyrefly now uses a line-number fallback to match definitions correctly.

• #3378: Fixed exhaustive Enum variants not narrowing the type. When a Final Enum variant was checked with is not, the type was not narrowed out of the union, causing false positives in exhaustiveness checks.

• #3413: Fixed strict mode insisting on @override for standard dunders. Pyrefly now skips missing-override-decorator for dunders inherited from object, as adding @override to __repr__, __eq__, etc., is pure noise.

• #3455: Fixed crash when overload residual capture included PartialQuantified vars. The solver now correctly handles partial vars in overload residuals, preventing panics.

• #3392: Fixed Self@[Enum] not being properly narrowed. For an exhaustive match on an enum type within an instance method, the self argument wasn't being narrowed as expected. Enum member subtraction now preserves and handles SelfType, allowing exhaustive enum match self fallbacks to narrow to Never.

• #3299: Fixed incorrect type inference after __setitem__ / __getitem__. When a class's __setitem__ and __getitem__ signatures were asymmetric, Pyrefly incorrectly narrowed the assigned value. Subscript-assignment narrowing is now gated by symmetry checks, preventing false positives with custom container types.

• And more! #3446, #3448, #3396, #1492, #2451, #3431, #3210, #3381, #2547, #3147, #3524, #3506, #3519, #3343, #3505, #3369, #3344, #3400, #3394, #3221, #3514, #3520, #3544, #3458

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue [here](https://github.com/facebook/pyrefly/issues).

---

## 📦 Upgrade

`bash pip install --upgrade pyrefly==1.1.0-dev.1 `

### How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors

2. Run your code formatter of choice

3. pyrefly check --remove-unused-ignores

4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the [Pyrefly documentation](https://pyrefly.org/en/docs/error-suppressions/).

---

## 🖊️ Contributors this release

@stroxler, @rchen152, @ndmitchell, @yangdanny97, @kinto0, @jorenham, @asukaminato0721, @migeed-z, @samwgoldman, @lolpack, @grievejia, David Tolnay, @connernilsen, @arthaud, @maggiemoss, @NathanTempest, @f1sherFM, @mfish33, @lordhaa123, Anqi Wu, @javabster, @rexledesma, @MackDing, Brian Rosenfeld, @fylux, @YBJ0000, @arpitjain099, @EpicEric, @NarxPal, Philippe Bidinger, @knQzx, @yeetypete, @GHX5T-SOL, Tejesh Mehta, @fangyi-zhou, @LeSingh1, @P-r-e-m-i-u-m, @Arths17, @sjh9714, @mdbernard

---

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.

Status: STABLE Release date: 12 May 2026

Pyrefly v1.0.0 is here!

We're thrilled to announce that Pyrefly has reached its stable 1.0.0 release! Since our beta release in November 2025, we've fixed hundreds of bugs, improved performance, and added lots of new functionality. Pyrefly is already the default type checker for Instagram at Meta and has been adopted by other large production codebases like PyTorch and JAX. Today, we're making it official: Pyrefly is production ready.

This would not have been possible without our amazing open-source community. To everyone who filed GitHub issues, submitted pull requests, gave us feedback at conferences, or joined us on Discord: thank you. Your contributions shaped this release.

These release notes cover the major highlights since our beta release. For the full history, see our past weekly release notes.

Performance Improvements

We've continued to push Pyrefly's performance since the speed improvements we shared in February. Since beta:

• 2–125x faster updated diagnostics after saving a file (no, that’s not a typo!). Thanks to fine-grained dependency tracking and streaming diagnostics, updates now consistently arrive in milliseconds
• 20–36% faster full type checking on large projects like PyTorch and Pandas
• 2–3x faster initial indexing when Pyrefly first scans your project
• 40–60% less memory usage during both indexing and incremental type checking

(Tested on an M4 Macbook Pro using open-source benchmarks from type_coverage_py and ty_benchmark.)

Compare the performance of Pyrefly and other Python type checkers on our regularly updated benchmarking suite, which runs against 53 popular Python packages.

Configuration Presets

A new preset configuration option provides named bundles of error severities and behavior settings.

See the configuration docs for details.

Onboarding Experience

We’ve made improvements to the out-of-the-box experience for projects without a pyrefly.toml.

• Automatic config synthesis — if you have a mypy or pyright config, Pyrefly automatically migrates your settings and synthesizes an appropriate in-memory Pyrefly config. (This is the same migration that pyrefly init would commit to disk.)
• Basic preset for unconfigured projects — projects with no type checker config get the lightweight “basic” preset, which surfaces only high-confidence errors.
• VS Code status bar — the status bar shows the active preset — e.g. Pyrefly (Basic) or Pyrefly (Legacy) — so you always know which mode is active.
• Type error display settings — new VS Code settings let you control which preset applies to unconfigured files and suppress all diagnostics workspace-wide.

Type Checker Improvements

We've been hard at work making the type checker robust and feature-complete, with a focus on driving down false positives and improving type quality in real-world code bases. Here are some highlights:

• Across the board we've eliminated many sources of false positives in enums, dataclasses, ParamSpec, descriptors, and more.
• Support has been added for more type narrowing patterns, including preserving narrows in nested scopes and recognizing container membership checks.
• Overload resolution was substantially reworked to handle more real-world patterns.
• Pyrefly’s conformance to the Python typing specification has improved from 70% at beta to over 90% today.
• We've added experimental support for tracking tensor dimensions through PyTorch models — see "What's Next" below.

LSP & IDE Improvements

• We've added new refactoring capabilities like Safe Delete (with reference checking) and bulk source.fixAll.
• Navigation is more precise, and hover cards surface richer information for imports, tuples, and NamedTuples.
• Workspace mode is more stable, with multiple crash fixes and improved diagnostic publishing.

Framework & Notebook Support

• Django — Pyrefly has improved support for model relationships, fields, and views, and understands factory_boy factories.
• Pydantic — Pyrefly models Pydantic's runtime behavior more faithfully, with support for lax mode and range constraint validation, and handles more of the Pydantic ecosystem: RootModel, pydantic-settings, and pydantic.dataclasses.
• Pytest integration — We've added Code Lens run buttons for test functions, as well as code actions to annotate fixture return types and parameters.
• Jupyter notebooks — .ipynb IDE support has reached full parity with .py files, with rename, find references, code actions, and document symbols all supported.

Complementary Tooling

Pyrefly ships with tools to aid with adopting type checking in an existing codebase. Two new tools since beta:

• pyrefly coverage report outputs a JSON report with annotation completeness and type completeness metrics per function, class, and module, so you can track coverage over time.
• Baseline files let you snapshot current errors into a JSON file so only new errors are reported, as an alternative to inline suppression comments.

Updated Version Policy

Going forward, we’ll switch from a weekly to monthly cadence for minor (1.x.0) releases, with patch releases in between as-needed for critical fixes. We’ll continue providing release notes for minor versions, so you can see what’s new in each release.

What's Next

• Tensor shape checking — Experimental support for tracking tensor dimensions through PyTorch models and catching shape mismatches statically. Learn more.
• Pyrefly + AI agents — Pyrefly's speed makes it a natural verification step in agentic workflows. See our guide on adding Pyrefly to your agentic loop.
• Continued improvements — We'll keep expanding library support, reducing false positives, and iterating on your feedback. Let us know what you need on GitHub or Discord.

Thank you to all our contributors!

The following people have directly contributed at least once to the development of Pyrefly since our first Alpha release.

@aahanaggarwal, @aaron-ang, @abdallhfattah, @Abel981, @abesto, @abhi-jha, @ABohra3, @Adamkaram, @Adist319, @adsi7698, @AHA705, @ahornby, @airvzxf, @ajaymiranda, @akmalsoliev, Alan Du, @Alex-Aron, Alok Priyadarshi, Alvaro Leiva Geisse, @AmalenduManoj, Anass Al-Wohoush, Anqi Wu, @ArchieBinnie, @arnav-jain1, @arosenber, @arthaud, @Arths17, @AryanBagade, @asm89, @asukaminato0721, @austin3dickey, @avikchaudhuri, Ben Carr, @bharath-2022, @bigfootjon, @bluetech, @bowiechen, @brchien, Brian Rosenfeld, @bv-saketha-rama, @capickett, Carlos Fernandez, @cbarrete, @cclauss, @charliecloudberry, @cjlongoria, Claudionor Santos, @connernilsen, @CookieComputing, @cooperlees, @cybardev, @DanielNoord, @danielocfb-test, @darricklaidin, David Tolnay, @davidbarsky, @ddrcoder, @dhleong, Dhruv Mongia, @diliop, @disrupted, @dluo, @Dogacel, @ducdetronquito, @ericweb2, @fangyi-zhou, @fannheyward, @fatelei, @github-main-user, @grantlouisherman, @grievejia, @gvozdvmozgu, @hanzel-sc, @hashiranhar, @hugovk, @iamPulakesh, @IDrokin117, @immanuel-peter, @Imran-S-heikh, @InSyncWithFoo, @ipr-ams, Ivan Loskutov, @j-piasecki, @jack-mcivor, @jackulau, @jagill, Jaimin Brahmbhatt, @JakobDegen, @javabster, @jchanke, Jess Wass, @jorenham, Jun Hao, @jvansch1, @K1T3K1, @KaranPradhan266, @Karman-singh15, Keito Uchiyama, @kinto0, @kitagry, @knQzx, @krathul, @krikera, @Krishnachaitanyakc, @kshitijgetsac, @kv9898, Li Shen, lianne, @lolpack, @Louisvranderick, @maggiemoss, @maifeeulasad, @maldoinc, @MarcoGorelli, @markmarkmarkthebest, @martindemello, @melvinhe, Miae Kim, @michaelcortese, @michel-slm, Mick Killianey, @migeed-z, Miles Conn, @mohesham88, Morgan Bartholomew, @MountainGod2, @mrsobakin, @mstykow, @mvanhorn, @NathanTempest, @ndmitchell, @nhawkes, @nikita-ashihmin, @nitinsingh-meta, @NSPC911, @ogios, @oopscompiled, @oriori1703, Owen Valentine, @oyarsa, @pavelzw, @pawelstrzmeta, @pawlowskialex, @PhilHem, @prasannavenkateshgit, @praskr-wisdom, @Prathamesh-tech-eng, @pswitchy, @pt2302, @QEDady, @QuantumManiac, @quark-zju, @Raf-Hs, @Rayahhhmed, @rchen152, @rchiodo, @regexyl, @rexledesma, @ricardoleal20, Robert Rusch, @robertoaloi, Ron Mordechai, @rubmary, @runlevel5, @salmanmkc, @salvatorebenedetto, @SamChou19815, @samwgoldman, @sandeshbhusal, @sargun, @Sehat1137, @self-sasi, @serephus, @sgavriil01, @shayne-fletcher, @shining44, @ship-it-ship-it, @shuv-amp, @sifex, @simonhollis, @singiamtel, @ska-kialo, @slawlor, @Solumin, @stanleyshen2003, @stroxler, Takuma Iwaki, @Tamchuk, @tannguyencse19, @tejasreddyvepala, @terror, @TheRustyPickle, @thomaspolasek, Tianhan Lu, @tkaleas, @tsembp, @ukautz, @Viicos, @vinnymeller, Vladimir Matveev, Weixi Ma, @Wilfred, Will Li, @willylau, @xaskii, @xl4624, @yamgent, @yangdanny97, @yeetypete, @yslim-030622, @zachmullen, @zanieb, @zbowling, @Zeko369, @zertosh, @zhuolix, @zpao, @zriser, @zsol

Full Changelog: https://github.com/facebook/pyrefly/compare/0.64.0...0.64.1

Status : BETA Release date: May 05, 2026

Pyrefly v0.64.0 bundles 190 commits from 20 contributors.

✨ New & Improved

🐛 bug fixes

We closed 15 bug issues this release 👏

• #3057: Fixed an issue where string concatenation with the + operator was incorrectly flagging str as not assignable to LiteralString attributes. Pyrefly now preserves LiteralString style when adding two explicit string literals and uses implicit style otherwise.
• #105: Fixed premature type pinning in function calls where arguments were incorrectly narrowed before all constraints were solved. For example, foo(x, y) with x: int | None and y: int | None no longer incorrectly narrows x to None when passed to a generic foo[T](a: T, b: T).
• #3198: Fixed pyrefly suppress --remove-unused which was not actually removing unused error suppressions. The command now correctly processes the --remove-unused flag.
• #3024: The language server now advertises source.fixAll.pyrefly in addition to source.fixAll, allowing users to selectively enable or disable Pyrefly's fix-all actions in editors that support LSP code action kinds.
• #2819: Fixed incorrect variance errors when using generic classes like Pydantic's RootModel in lax mode. Missing type arguments now degrade to Any instead of raising errors, matching our handling of other incomplete types.
• #3000: Fixed "find references" failures in Cursor and other editors caused by relative imports in site-packages not resolving correctly when a pyproject.toml existed at the project root.
• #2563: Fixed go-to-definition on relative imports in virtual environment site-packages, which was returning null because the project root's import path was matching before the more specific site-package prefix.
• #3193: Fixed an error where list["A|B"] was incorrectly rejected as not-a-type. Type argument subscripts are now bound as type expressions even in value context, allowing forward-ref strings to be parsed.
• #3286: Fixed exponential memory blowup when type-checking deeply-nested dict literals, which could cause VSCode to be killed by the OS. Memory usage for a depth-25 dict dropped from ~7.7 GB to ~239 MB.
• #3261: Fixed a false positive bad-class-definition when a dataclass field was assigned inside a @classmethod or __init_subclass__. Pyrefly was incorrectly extracting these as dataclass fields, even though Python's dataclasses.dataclass ignores them at runtime.
• #2914: assert statements now flag a non-callable __bool__ on the test expression, closing a gap that previously only caught the issue inside if, while, and ternary expressions.
• #2867: Fixed urlunparse being inferred as returning Literal[b''] instead of str. The fix reworks as_superclass so tuple-like NamedTuple subclasses are upcast through their erased tuple element types, which stops ParseResult from spuriously matching Iterable[None] and selecting the bytes overload.
• #3266: Added a quick fix for the existing "Did you mean Foo.BAR?" diagnostic note for missing enum members, turning the suggestion into a code action that rewrites the surrounding string literal.
• #3230: Numeric parameter defaults now preserve their original spelling (e.g. 0o777) in hover and signature display rather than being normalized to a decimal value.
• #3302: Added a path field to the pyrefly report JSON ModuleReport, restoring compatibility with typestats.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.64.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors 2. run your code formatter of choice 3. pyrefly check --remove-unused-ignores 4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the [Pyrefly documentation](https://pyrefly.org/en/docs/error-suppressions/)

🖊️ Contributors this release

@stroxler, @rchen152, @migeed-z, @grievejia, @samwgoldman, @kinto0, @asukaminato0721, @jvansch1, @NathanTempest, @avikchaudhuri, @connernilsen, Carlos Fernandez, David Tolnay, @jorenham, @rexledesma, @arthaud, @pawlowskialex, @QuantumManiac, @knQzx, @QEDady

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.

Full Changelog: https://github.com/facebook/pyrefly/compare/0.63.0...0.63.1

Status : BETA Release date: April 27, 2026

Pyrefly v0.63.0 bundles 129 commits from 26 contributors.

✨ New & Improved

🐛 bug fixes

We closed 9 bug issues this release 👏

• #3099: Fixed an issue where property setters and deleters inflated typable counts in pyrefly report by incorrectly counting their trivial -> None return types.
• #3098: Fixed an issue where overloads in pyrefly report were not deduplicated, causing parameters and callable signatures to be counted multiple times and inflate coverage metrics.
• #3067: Fixed an issue where the type display path was dropping the unpack marker (*) for direct TypeVarTuple arguments, causing Shape to render bare instead of *Shape.
• #3040: Fixed an issue where properties on metaclasses were not taking precedence over properties on the class during class-level attribute access, causing false bad-assignment and bad-return errors.
• #3150: Fixed an issue where type aliases were inflating type coverage in pyrefly report by being counted as typable entities.
• #3041: Fixed a panic during workspace/symbol requests on re-exported symbols with multi-byte UTF-8 characters, caused by using the canonical module's byte offset against the re-exporting file's buffer.
• #3109: Added a new unnecessary-type-conversion lint that warns when str(), int(), or float() is called on an argument that is already of that exact type, making the conversion redundant.
• #3187: Fixed a panic in pyrefly report when @no_type_check decorator was used, caused by a missing key lookup for skipped parameter annotations.
• #3090: Improved the unused-coroutine error message when an await expression already has await but produces a coroutine due to an incorrect return type annotation on the function definition.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.63.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors 2. run your code formatter of choice 3. pyrefly check --remove-unused-ignores 4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation

🖊️ Contributors this release

@rchen152, @migeed-z, @avikchaudhuri, @grievejia, @kinto0, @jorenham, @jvansch1, generatedunixname2066905484085733, @stroxler, @tejasreddyvepala, David Tolnay, @fangyi-zhou, @asukaminato0721, @lolpack, @NathanTempest, @connernilsen, @zbowling, @rubmary, @rexledesma, Anass Al-Wohoush, @javabster, @ABohra3, generatedunixname89002005232357, @tkaleas, @knQzx, generatedunixname89002005307016

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.

Status : BETA Release date: April 20, 2026

Pyrefly v0.62.0 bundles 87 commits from 23 contributors.

✨ New & Improved

🐛 bug fixes

We closed 12 bug issues this release 👏

• #3118: Fixed incorrect stub package recommendations for typeshed third-party libraries. Pyrefly now suggests the correct package name (e.g., types-python-dateutil for the dateutil module, not types-dateutil) by extracting the module→package mapping from the bundled typeshed archive, preventing potential typosquatting.
• #3081: Fixed NewType wrappers with NoneType bases being incorrectly rejected or treated inconsistently. NewType("NewNoneType", NoneType) is now accepted as a valid nominal type declaration, and plain None is correctly rejected where NewNoneType is required.
• #3052: Fixed false positive unexpected-keyword errors for named parameters before *args: P.args. Functions like call_with_retry(f, max_attempts=10, *args: P.args, **kwargs: P.kwargs) now correctly allow max_attempts to be passed as a keyword argument, matching mypy and pyright behavior.
• #3110: Fixed LSP server crashes when the client sends a position with a line number beyond the end of the buffer (e.g., after a DidChangeTextDocument race where the file was truncated). Out-of-range positions now map to EOF instead of panicking.
• #2912: Fixed false positive bad-argument-type for list(null_values.items()) when the return type hint is a union like Sequence[str] | list[tuple[str, str]]. Pyrefly now tries constructing the class with each union member independently and unions the results, ensuring the inferred type is assignable to the hint.
• #2644: Fixed false positive bad-argument-type when calling a method with AnyStr. Placeholder variables used during overload resolution are now saved and restored around overload calls, preventing AnyStr from being incorrectly specialized to str and polluting subsequent checks.
• #2872: Fixed false positive invalid-type-var for generic functions captured as closure default arguments. The Visit implementation for DefaultValue now calls visit instead of recurse, ensuring type-level visitors see the Type node stored in the default value.
• #3159: Fixed incorrect type inference for .value on enum members with non-data-type mixins. Mixins that don't define __new__ (e.g., class Meta: pass) are no longer treated as data type mixins, so Foo.bar.value correctly returns Literal[1] instead of Meta.
• #3161: Fixed false positive bad-argument-type for overloaded functions with vararg unpacking (e.g., *args: *tuple[int, str]). Type check errors for unpacked varargs are now sent to call_errors instead of arg_errors, so they don't cause the overload to be incorrectly rejected.
• #3047: Fixed false positive bad-specialization when matching a type variable against a union like N | Iterable[N]. Pyrefly now uses snapshot-based rollback when trying each union member, ensuring specialization errors from one branch don't leak into the final result if another branch succeeds without errors.
• And more! #3122, #3080, #3074

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.62.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors 2. run your code formatter of choice 3. pyrefly check --remove-unused-ignores 4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation

🖊️ Contributors this release

@rchen152, @stroxler, @migeed-z, @jorenham, @samwgoldman, @connernilsen, @NathanTempest, @kinto0, @jvansch1, @fangyi-zhou, @tejasreddyvepala, David Tolnay, generatedunixname2066905484085733, @mstykow, @AHA705, @Arths17, @grievejia, Claudionor Santos, @austin3dickey, @robertoaloi, @salvatorebenedetto, @iamPulakesh, generatedunixname89002005307016

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.

Full Changelog: https://github.com/facebook/pyrefly/compare/0.61.0...0.61.1

Status : BETA Release date: April 13, 2026

Pyrefly v0.61.0 bundles 85 commits from 21 contributors.

✨ New & Improved

🐛 bug fixes

We closed 9 bug issues this release 👏

• #3031: Fixed a crash in mypy_primer caused by a variable leak in LitEnum — types are now deep-forced before storage to prevent leaking vars into the solver.
• #2915: Division, floor division, and modulo by literal 0 are now flagged as errors, catching ZeroDivisionError at static analysis time instead of runtime.
• #3009: Fixed false positive unused-variable warnings for variables used exclusively within f-string format specifiers (e.g., f"{key:<{max_len}}"). The AST visitor now correctly descends into format_spec nodes.
• #2799: Fixed false positive [missing-attribute] errors for dict.setdefault(key, []).append(val) on unannotated dicts. Overload resolution now creates fresh partial variables for each overload, preventing incorrect pinning.
• #2991: Fixed Pydantic lax-mode rewriting re.Pattern[str] to Pattern[LaxStr] and rejecting re.Pattern[str]. Regex patterns now expand to re.Pattern[T] | T instead of recursively widening the inner type.
• #2916: Fixed runtime TypeError from multiple inheritance with conflicting __slots__ (same slot names). Pyrefly now detects and reports this layout conflict during class metadata computation.
• #2917: Fixed runtime TypeError from multiple inheritance with conflicting __slots__ (different slot names). Pyrefly now detects non-empty __slots__ in multiple bases and reports the conflict.
• #3064: Fixed false positive when using issubclass() after isinstance() narrowing with custom metaclasses (e.g., Django's ModelBase). Metaclass instances are now correctly accepted as valid class objects.
• #3030: Fixed false positive LiteralString type error in map(str.strip, ...). Overloads with narrower self-type annotations are now filtered out during unbound method resolution.

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.61.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors 2. run your code formatter of choice 3. pyrefly check --remove-unused-ignores 4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation

🖊️ Contributors this release

@rchen152, @migeed-z, @javabster, generatedunixname2066905484085733, @rubmary, @kinto0, @lolpack, @asukaminato0721, @knQzx, David Tolnay, @yangdanny97, @Arths17, @tejasreddyvepala, @salvatorebenedetto, @rchiodo, @stroxler, @samwgoldman, @arthaud, @fangyi-zhou, @NathanTempest, generatedunixname89002005307016

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.

Fixes exponential memory usage on unannotated dictionaries in 0.60.1.

Full Changelog: https://github.com/facebook/pyrefly/compare/0.60.1...0.60.2

Full Changelog: https://github.com/facebook/pyrefly/compare/0.60.0...0.60.1

Status : BETA Release date: April 06, 2026

Pyrefly v0.60.0 bundles 168 commits from 28 contributors.

✨ New & Improved

🐛 bug fixes

We closed 27 bug issues this release 👏

• #2976: Fixed an issue where yield from with a union return annotation (e.g., Iterator[tuple[Any, ...]] | Generator[dict[str, Any], None, Unknown]) incorrectly reported invalid-yield because the union members were not being decomposed before checking assignability.
• #2968: Fixed a false positive bad-argument-type error when using metaclasses — type[Banana | Grape] is now correctly assignable to FruitMeta when Banana and Grape inherit from Fruit(metaclass=FrustMeta).
• #2402: Fixed an issue where Pyrefly excluded all files when the project lived inside a hidden directory (e.g., ~/.codex/worktrees/XXXX/project/) because the **/.[!/.]*/** glob pattern matched hidden directory components anywhere in the absolute path, including ancestors above the project root.
• #2863: Fixed an issue where bounded type variables in match subjects resolved to their bound instead of the actual narrowed type — tuple match subjects like match x, y: now correctly narrow individual variables by their corresponding sub-patterns.
• #2980: Fixed an issue where namedtuple with a field named cls caused type warnings because the field collided with the synthesized __new__ method's first parameter — the internal parameter is now _cls.
• #2922: Fixed an issue where applying @dataclass to an Enum subclass was not rejected — this is now correctly reported as BadClassDefinition because Python's dataclasses module does not support Enum subclasses (runtime TypeError).
• #2923: Fixed an issue where applying @dataclass to a TypedDict subclass was not rejected — this is now correctly reported in the canonical class_metadata_of path, and dataclass_metadata is cleared after reporting the error.
• #2921: Fixed an issue where applying @dataclass to a Protocol subclass was not rejected — this is now correctly reported because Protocol classes define structural interfaces, not data containers.
• #2975: Fixed an issue where the provide-type endpoint returned Unknown for type aliases — operator expressions now return result types instead of dunder method signatures, and type alias names in function signatures are now module-qualified.
• #2982: Fixed a stack overflow crash when checking fuzzed code with mutually recursive type aliases like type T = U; type U = T — when a cycle is detected, wrap_type_alias now returns an error type instead of the cyclic body.
• And more! #2987, #2610, #2874, #2857, #1950, #2741, #2983, #2919, #2979, #2973, #1982, #2910, #2950, #2978, #2875, #2986, #2972, #2852

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.60.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation

🖊️ Contributors this release

@stroxler, @yangdanny97, @migeed-z, @rchen152, @javabster, @asukaminato0721, @kinto0, @avikchaudhuri, @arthaud, @tejasreddyvepala, @lolpack, @fangyi-zhou, @Louisvranderick, @runlevel5, @yeetypete, @NathanTempest, @stanleyshen2003, Morgan Bartholomew, @connernilsen, @salvatorebenedetto, @kshitijgetsac, @Raf-Hs, Mick Killianey, David Tolnay, @dhleong, @Arths17

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.

Fixed a performance regression in 0.59.0.

Full Changelog: https://github.com/facebook/pyrefly/compare/0.59.0...0.59.1

Status : Beta
Release date: March 30, 2026

Pyrefly v0.59.0 bundles 153 commits from 20 contributors.

✨ New & Improved

🐛 bug fixes

We closed 16 bug issues this release 👏

• #2026: Fixed an issue where recursive bounded generics were incorrectly reported as object, ensuring accurate type checking.
• #2812: Resolved a false positive invalid-type-var error when persisting the get method of a fully-annotated dict.
• #2804: Fixed an implicit-any false positive that occurred with TypedDict items, improving code readability.
• #2868: Pyrefly now correctly recognizes while...else statements with returns in the else clause as exhaustive.
• #2814: Enhanced hover information for datetime.datetime imports to display constructor signatures and docstrings.
• #2896: Fixed a bad-argument-type error that occurred when using double-underscore arguments.
• #2893: Pyrefly now correctly handles dict Literal key types as subtypes of str key types.
• #2865: Resolved an issue where tuple subclasses with overridden __getitem__ were not recognized.
• #2871: Fixed a false positive error when using isinstance with type | X.
• And more! #2444, #1270, #2900, #2862, #2853

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.59.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation

🖊️ Contributors this release

@rchen152, @lolpack, @yangdanny97, @stroxler, @samwgoldman, @jvansch1, @kinto0, @connernilsen, @asukaminato0721, @migeed-z, @arthaud, @grievejia, @rubmary, @Adist319, David Tolnay, @yslim-030622, @tejasreddyvepala, @mvanhorn, @MountainGod2

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.

Status : BETA Release date: March 24, 2026

Pyrefly v0.58.0 bundles 190 commits from 24 contributors.

✨ New & Improved

🐛 bug fixes

We closed 20 bug issues this release 👏

• #2452: Fixed a memory leak where the language server's memory usage climbed by ~3GB on every pyproject.toml save. Stale loader entries are now garbage-collected at commit time, keeping memory usage stable across configuration reloads.
• #2826: Fixed an issue where pattern matching on an attribute (e.g., match c.items: case [_]:) incorrectly narrowed the base variable to Never. Sequence pattern narrowing operations now correctly propagate facet subject information.
• #2520: Fixed false positive "variable may be uninitialized" errors in nested if/elif branches. Exhaustive if/elif chains are now recognized as terminating for uninitialized local checks, just like match statements.
• #1518: Fixed an issue where exhaustive if/elif chains over enum variants still reported "unbound-name" errors. The exhaustiveness key is now passed through non-exhaustive fork merging so the synthetic fallthrough path is recognized as impossible.
• #1286: Fixed exhaustiveness checking in match statements to work with isinstance-based narrowing and mixed is/isinstance patterns. Narrowing to Never is now always sound for flow analysis regardless of the type being narrowed.
• #2833: Fixed an issue where dict.get(k) with an incorrect argument type returned Unknown instead of the correct return type. Overloads are now eliminated by arity before applying return type hints, giving you precise return types even when calls have errors.
• #823: Fixed ParamSpec forwarding between generic helpers. When one generic helper forwards *args: P.args, **kwargs: P.kwargs to another, the solver now correctly validates the forwarding pattern instead of producing bogus "Expected P to be a ParamSpec value" errors.
• #2309: Fixed false positive bad-override errors when subclassing str and adding optional parameters to overridden methods. Inapplicable parent overloads (e.g., LiteralString overloads when the subclass is not LiteralString) are now filtered out during override checking.
• #1083: Fixed false positive "No matching overload" errors when accessing descriptors with overloaded __get__ through type[T] where T is bounded. The descriptor base now preserves the ClassBase wrapper to correctly produce type[T] instead of type[A].
• #2007: Fixed false positive unused variable warnings when reassigning parameters in loops or when assigning to global/nonlocal variables. The unused variable analysis now correctly tracks these assignment patterns.
• And more! #2419, #1252, #2043, #2218, #650, #2164, #1635, #2168, #1005, #2655

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.58.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors 2. run your code formatter of choice 3. pyrefly check --remove-unused-ignores 4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation

🖊️ Contributors this release

@stroxler, @rchen152, @yangdanny97, @grievejia, @kinto0, @migeed-z, @jvansch1, @ndmitchell, @samwgoldman, @maggiemoss, @arthaud, @connernilsen, @fangyi-zhou, @avikchaudhuri, @asukaminato0721, @jackulau, @PhilHem, @Rayahhhmed, @oyarsa, generatedunixname2066905484085733, David Tolnay, Brian Rosenfeld, @rubmary, @rchiodo

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.

Fixed a bug that could cause Pyrefly to hang.

Status: Beta
Release date: March 16, 2026

Pyrefly 0.57.0 bundles 116 commits from 17 contributors.

✨ New & Improved

🐛 bug fixes

We closed 24 bug issues this release 👏

• #2696: Fixed an issue where Pyrefly’s LSP incorrectly flagged from typing import NewType as unused, even when NewType(...) was referenced.
• #2743: Fixed an issue where TypedDict fields named items/values prevented access to the corresponding dict.items() / dict.values() methods via attribute lookup.
• #2745: Fixed an issue where chained/nested narrowing expressions (e.g. multi-clause and conditions) failed to narrow correctly when using negative subscript indices.
• #2737: Fixed an issue where functools.partial(...) results couldn’t be assigned back to a Callable typed with a ParamSpec, causing a false-positive type error.
• #2650: Fixed an issue where a Protocol parameterized by ParamSpec[...] wasn’t considered compatible with an equivalent “gradual” protocol using *args: Any, **kwargs: Any.
• #2334: Fixed an issue where calling __init__ on parametrized bound methods could trigger a false-positive type error due to incorrect attribute lookup behavior.
• #2731: Fixed an issue where super() calls to abstract methods that do have a concrete runtime body were incorrectly reported as missing-attribute / abstract-call errors.
• #828: Fixed an issue where reading a conditionally-initialized variable didn’t “commit” the initialization, leading to redundant follow-on “may be uninitialized” errors.
• #835: Fixed an issue where type information for subclasses wasn’t handled correctly, leading to failures when type-checking subclass relationships.
• And more! #2522, #1800, #2736, #2382, #913, #1397, #2261, #2669, #2744, #2739, #1575, #903, #1043, #1429, #2607

Thank-you to all our contributors who found these bugs and reported them! Did you know this is one of the most helpful contributions you can make to an open-source project? If you find any bugs in Pyrefly we want to know about them! Please open a bug report issue here

📦 Upgrade

pip install --upgrade pyrefly==0.57.0

How to safely upgrade your codebase

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them. After upgrading, follow these steps:

1. pyrefly check --suppress-errors
2. run your code formatter of choice
3. pyrefly check --remove-unused-ignores
4. Repeat until you achieve a clean formatting run and a clean type check.

This will add # pyrefly: ignore comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

Read more about error suppressions in the Pyrefly documentation

🖊️ Contributors this release

@stroxler, @grievejia, @yangdanny97, @migeed-z, @jvansch1, @rchen152, @asukaminato0721, @maggiemoss, @arthaud, @lolpack, @samwgoldman, @Adist319, David Tolnay, @avikchaudhuri, @rubmary, @javabster

Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed. Highlights from patch release changes that were shipped after the previous minor release are incorporated here as well.