Pyrefly v1.4.0

Release date: October 14, 2026

Pyrefly v1.4.0 bundles 1191 commits from 66 contributors.

---

Release Highlights

Language Server

• The VS Code extension now runs the Pyrefly from your environment. By default, the extension launches the Pyrefly installed in your active Python environment (for example, your project's .venv), so your editor and your command line use the same version. If the environment has no Pyrefly, the extension falls back to its bundled binary. Set pyrefly.pyreflyExecutable to bundled to keep the old behavior. See Pyrefly binary selection.

Configuration & CLI

• uv workspace members are now type checked. In a uv workspace, the interpreter puts each member's source directory on sys.path as an editable install. Pyrefly treated those directories as installed packages and skipped them, so errors in workspace members went unreported. Pyrefly now checks editable sources inside your project, while regular site-packages stay excluded.

Type Checking

• Easier migration from BasedPyright. Pyrefly reads basedpyright sections in pyproject.toml and applies the matching type checking mode preset.
• New opt-in checks for untyped code. New error kinds such as unknown-member-type, unknown-return-type, untyped-function-decorator, and uninitialized-instance-variable help you find where Any enters your code.

Tensor Shapes

• JAX shape stubs on PyPI. This is the first stable release that ships JAX shape stubs as the jax-pyrefly-stubs package.

---

⚠️ Behavior Changes

These may change your editor setup or surface new errors in code that checked cleanly under v1.3.0.

• The VS Code extension now uses the Pyrefly in your active environment by default instead of its bundled binary. If your environment pins an older Pyrefly, the editor now runs that version. The Pyrefly language server output channel shows which binary was chosen and why.
• Pyrefly now checks the source of uv workspace members (editable installs inside your project). Errors in those packages that were hidden before can now appear.
• --typeshed-path now replaces the bundled typeshed entirely instead of overlaying it.
• The incompatible-overload-residual error kind is renamed to incompatible-overload-argument. The old name still works as a deprecated alias.
• site-package-path is renamed to site-packages-path. The old name still works.

---

✨ New & Improved

Type Checking

• Pyrefly now recognizes basedpyright configuration sections in pyproject.toml and applies appropriate type checking mode presets, making it easier to migrate from BasedPyright.
• TypedDict handling has been significantly improved: generic extra_items are now instantiated correctly, extra items can supply missing arguments, and definitely_seen calculation in callable checking has been fixed.
• TypeVar restriction checking is now enforced even when the expected type is gradual, preventing silent violations of TypeVar bounds and constraints when Any appears in the expected type.
• Improved handling of overloaded function arguments in generic function calls through a new overload table mechanism, replacing the previous residual-based approach. The incompatible-overload-residual error kind has been renamed to incompatible-overload-argument (the old name remains as a deprecated alias).
• Variance inference has been improved with fixes for nested variance reliability bugs and explicit stored variance evidence.
• Property decorator validation now reports invalid signatures with extra required parameters.
• Added opt-in uninitialized-instance-variable check for annotated instance attributes never assigned in __init__ or class body, including @dataclass(init=False) fields.
• Improved higher-order function call handling with quantified finalization and better overload branch capture.
• functools.partial now uses standard quantified finalization and handles generic overload targets.
• Improved ParamSpec variance in generic comparisons and handling of generic callable residuals.
• Added support for propagating divergence through compound statements to detect unreachable code after if/else blocks where all paths diverge.
• Added support for evaluating sys.version_info comparisons against tuples with release levels like (3, 14, 0, "beta").

Type Checking Fixes

• Overload evaluation now forces per-overload argument types before rolling back variables, so variables are no longer pinned by accident.
• Overload evaluation step 5 (argument materialization) now runs for implicit descriptor __get__ calls.
• Invalid type(...) calls in annotations now suggest valid type forms like types.NotImplementedType, types.EllipsisType, None, types.ModuleType, or type[MyClass].
• Invalid function calls in return annotations now produce clearer error messages.
• Unknown unions in class bases now accept valid known classes while recording dynamic bases.
• Conditionally imported base classes now keep the known class while recording a dynamic base.
• Tuple constructor type variables no longer leak when the constructor is passed as a higher-order factory callable.
• Overloaded constructors no longer leak type parameters through gradual arguments.
• Version-gated returns now preserve configured reachability.
• Environment-dependent branch tests (like TYPE_CHECKING = False) no longer report their suites as unreachable.
• Descriptor setter override checking now checks every overload.
• Module resolution now honors first-match-wins between single-file modules and packages in later roots.
• Never containers (list[Never], dict[Never, Never], etc.) are now recognized as falsy.
• Unpacking an overloaded tuple now combines branches position by position.
• Assigning to an overloaded type now succeeds when the value fits any branch.
• Facet narrowing now narrows overloaded values by ruling out branches.
• Attribute access and subset checks on overloaded types are more accurate.
• Overload selection now ignores type variables that appear only in the return type.
• Overloads that violate TypeVar restrictions under a gradual expected type are now rejected.
• Return type variables of overloaded protocol methods in invariant classes are now handled correctly.
• Union type arguments in indirect diamond inheritance are now compared without regard to member order.
• max/min calls with key= and default= no longer report argument errors from rejected union hint members.
• Attribute facets are now rebased correctly when the base type is replaced.
• Annotated metadata is no longer type checked, which removes spurious errors.
• Methods typed as a union with Any, or whose decorator returns T | Any, now bind correctly.
• A custom __new__ inherited from an intermediate NamedTuple subclass is now handled correctly.
• Identity and membership tests with an Any operand now infer bool.
• Soft errors no longer drive constructor, default, and decorator checks.
• A python-version below 3.5 is now rejected with an error instead of crashing.

Language Server

• The VS Code extension now launches the Pyrefly installed in your active Python environment by default, and falls back to the bundled binary. A new pyrefly.pyreflyExecutable setting (from-environment or bundled) controls this. Selecting a different interpreter restarts the server with the new binary when it changes.
• Pyrefly now watches explicit configPath settings and reloads configuration when those files change.
• Hover now prefers interface (.pyi) docstrings over implementation (.py) docstrings when both exist.
• Go-to-definition for standard library symbols now searches the interpreter's stdlib for .py files.
• Go-to-definition now prefers stub definitions over unresolved __all__ entries and handles re-export cycles.
• Go-to-definition now works for TypedDict subscript keys.
• LSP rename now includes attribute assignments and deletions across files.
• Added LSP quick-fix code action for removing unused ignores.
• Added LSP registration for workspace/didChangeConfiguration on python section.
• Fixed language server to answer startup requests with workspace settings instead of defaults.
• Fixed language server deadlock when configuration response triggers file watcher registration.
• Added TSP pyrefly/typeFacts request for batch type queries.
• Fixed TSP --config to pin config for every file.
• Added code action videos to IDE features documentation.
• Fixed attribute definition index recording for assignment and deletion targets in rename.
• Added object attributes to LSP attribute completion, ranked after class attributes.
• Callable class attributes now bind self when first parameter is the containing class.

Polars Support

• select and with_columns now handle both positional and keyword arguments correctly, preserving schema information.
• Added validation for Polars conditional predicates, duplicate with_columns outputs, and sole-argument list expansion rules.
• Improved Polars column-width tracking with OutputCount enum to distinguish provable width from unknown width.
• Added support for Polars pl.col. attribute completion, suggesting columns from the enclosing DataFrame operation.
• Added validation for column names in Polars filter, sort, unique, and drop_nulls methods.

Django Support

• QuerySet.annotate() now preserves keyword annotation attributes on result rows for attribute lookup and LSP completion.
• Fixed Django relation to= keyword argument resolution.
• Fixed Django ForeignKey keyword-form to= resolution.

Configuration & CLI

• uv workspace members (editable installs inside the project) are now checked instead of being excluded as site packages (#2667).
• Added pyrefly completion command to generate shell comp...

Pyrefly v1.4.0-dev.4

Full Changelog: 1.4.0-dev.3...1.4.0-dev.4

Pyrefly v1.4.0-dev.3

Release date: October 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.4.0-dev.3 bundles 86 commits from 19 contributors.

This is a short snapshot — three days after v1.4.0-dev.2 — so it is a small release focused on unreachable-code reporting and language-server fixes.

---

✨ New & Improved

Type Checking

• Unreachable-code reporting continues to expand: Pyrefly now reports except clauses that can never be entered, redundant exception classes inside a reachable except clause, and dead code after a call that never returns.

Language Server

• Pyrefly migrated from its lsp-types fork to gen-lsp-types 0.11.0.
• Baselines now have the option to automatically remove fixed baselined errors on file save.

Other

• Build-system-supplied configuration is better documented, and module finder options moved into a struct.
• Agent invocation metadata is now shared and used for error telemetry.

---

🐛 Bug fixes

• #4825: Fixed a false bad-return for a generator function annotated Iterator[X] | T.
• #5073: Fixed a series of unreachability bugs that made it into the last release.
• #4668: Extension-less Python scripts, such as a shebang script named script rather than script.py, got no diagnostics in the editor. Their errors were computed and then dropped before publishing, because the default project-includes globs cannot match a path with no extension. These files are now reported, and they respect project-includes by matching as though they ended in .py.
• An unsaved file is now checked as the language the editor reports it to be, rather than always being assumed to be Python.
• An assignment to a field inherited from a frozen Pydantic model is now checked. The assigned value was skipped, so a type mismatch went unreported and the attribute narrowed to Never.
• The right-hand side of an attribute assignment is now always inferred. It was sometimes skipped, which hid errors in the assigned expression.

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.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, @connernilsen, @rchen152, @kinto0, @asukaminato0721, @samwgoldman, @grievejia, @shobhitmehro, @jakevdp, @nitishagar, @shahhamdihassan, @arthaud, @Trighap52, @maggiemoss, @dantrapp, @tonyyuyiding, @MarcoGorelli, @igorsugak, @NarxPal

---

🔬 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.

• JAX svd shape typing is improved.
• jnp.cross no longer accepts 2D vectors.

---

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

Pyrefly v1.4.0-dev.2

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.

Pyrefly v1.3.2

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.

Pyrefly v1.4.0-dev.1

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.

Pyrefly v1.2.1

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.

Pyrefly v1.3.1

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.

Pyrefly v1.3.0

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...

Pyrefly v1.3.0-dev.4

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.