Release date: October 14, 2026
Pyrefly v1.4.0 bundles 1191 commits from 66 contributors.
.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.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.basedpyright sections in pyproject.toml and applies the matching type checking mode preset.unknown-attribute-access, unknown-return-type, untyped-function-decorator, and uninitialized-instance-variable help you find where Any enters your code.jax-pyrefly-stubs package.These may change your editor setup or surface new errors in code that checked cleanly under v1.3.0.
--typeshed-path now replaces the bundled typeshed entirely instead of overlaying it.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.basedpyright configuration sections in pyproject.toml and applies appropriate type checking mode presets, making it easier to migrate from BasedPyright.extra_items are now instantiated correctly, extra items can supply missing arguments, and definitely_seen calculation in callable checking has been fixed.Any appears in the expected type.incompatible-overload-residual error kind has been renamed to incompatible-overload-argument (the old name remains as a deprecated alias).uninitialized-instance-variable check for annotated instance attributes never assigned in __init__ or class body, including @dataclass(init=False) fields.functools.partial now uses standard quantified finalization and handles generic overload targets.if/else blocks where all paths diverge.sys.version_info comparisons against tuples with release levels like (3, 14, 0, "beta").__get__ calls.type(...) calls in annotations now suggest valid type forms like types.NotImplementedType, types.EllipsisType, None, types.ModuleType, or type[MyClass].TYPE_CHECKING = False) no longer report their suites as unreachable.Never containers (list[Never], dict[Never, Never], etc.) are now recognized as falsy.max/min calls with key= and default= no longer report argument errors from rejected union hint members.Annotated metadata is no longer type checked, which removes spurious errors.Any, or whose decorator returns T | Any, now bind correctly.__new__ inherited from an intermediate NamedTuple subclass is now handled correctly.Any operand now infer bool.python-version below 3.5 is now rejected with an error instead of crashing.pyrefly.pyreflyExecutable setting (from-environment or bundled) controls this. Selecting a different interpreter restarts the server with the new binary when it changes.configPath settings and reloads configuration when those files change..pyi) docstrings over implementation (.py) docstrings when both exist..py files.__all__ entries and handles re-export cycles.workspace/didChangeConfiguration on python section.pyrefly/typeFacts request for batch type queries.--config to pin config for every file.Callable class attributes now bind self when first parameter is the containing class.select and with_columns now handle both positional and keyword arguments correctly, preserving schema information.with_columns outputs, and sole-argument list expansion rules.OutputCount enum to distinguish provable width from unknown width.pl.col. attribute completion, suggesting columns from the enclosing DataFrame operation.filter, sort, unique, and drop_nulls methods.QuerySet.annotate() now preserves keyword annotation attributes on result rows for attribute lookup and LSP completion.to= keyword argument resolution.ForeignKey keyword-form to= resolution.pyrefly completion command to generate shell completion scripts for fish, bash, and zsh.baseline-auto-update project setting that automatically prunes baseline files when saving files in the IDE.extends support for layered configurations.site-package-path to site-packages-path with backward compatibility.--typeshed-path to act as a full typeshed replacement instead of an overlay over the bundled typeshed.embed::Checker::try_new_with_typeshed to allow embedders to replace the bundled stdlib typeshed with in-memory .pyi stubs, useful for sandboxed interpreters like Monty.--report-glean-ownership flag to emit Glean ownership units for ACL-protected paths.--report-glean to write compact JSON instead of pretty-printed.unknown-attribute-access error kind for accessing attributes whose type is unknown.unknown-variable-type to report loop, unpacking, and with targets in addition to plain assignments.untyped-function-decorator check for decorators that return unknown types.untyped-class-decorator check for class decorators that return unknown types.default-severity for potential-bad-keyword-argument to be ignore as documented.bad-keyword-argument instead of potential-bad-keyword-argument.unknown-return-type for returning unknown values from unannotated functions and lambdas.untyped-namedtuple for collections.namedtuple without field types.assert-type-unspellable-subtype for unspellable types that are subtypes of expected type.unannotated-return false positive on __init__ methods.parking_lot for per-module computing locks, reducing memory footprint in large projects.Answers step directly instead of nested shared ownership.Require::Exports for implicit dependencies instead of Require::Everything.Elements wrappers where postponed annotations allow it.shape_extensions.Shaped and shape_extensions.shape_vars, allowing libraries to use shape types without requiring downstream users to use Pyrefly.no-any-return warnings to avoid false positives when the return type union already contains Any or Unknown.int and bool annotations.torch.unique stub.Parameter type.AdaptiveAvgPool2d size support and one-bound torch.randint overload.torch.is_tensor narrowing support.Series masks.jax.typing.ArrayLike shape-aware.np.interp type by adding missing __float__.jax-pyrefly-stubs. This is the first stable release that includes them.abs support in shape arithmetic.ndarray to be assignable to SupportsAbs by adding missing __abs__.+, -, *, //.jaxtyping configuration option to enable experimental jaxtyping shape checking support.jax.lax.scan shape inference for tuples of arrays.Tensor.T shape tracking now reverses axes.nn.Module registration types now fall back to the declared parameter type.Many of the changes above came from user reports: we closed 87 GitHub bug issues this release 👏 Here are some highlights:
TypeVarTuple were not assignable to gradual types. Pyrefly was incorrectly wrapping the tuple in an extra layer, causing tuple[int, *Ts] to be rejected when assigned to tuple[Any, *Ts].select and with_columns. Previously, select lost schema information for keyword expressions and with_columns lost it for positional expressions. Both now preserve schema correctly.@property decorators on methods with extra required parameters were not flagged as errors. Pyrefly now validates that property getters have the correct signature.__get__ calls. When a descriptor's argument type contained Any, the first overload would incorrectly win instead of properly evaluating all branches.stubgen. Generating a .pyi for a single file with a large transitive import closure previously used ~14 GB; it now uses comparable memory to pyrefly check by using Require::Exports instead of Require::Everything.bad-return error for generator functions with Iterator[X] | T return annotations. Pyrefly now correctly accepts return statements with non-None values in such generators.TypeIs[T] guards with free TypeVars producing no narrowing. When a TypeIs guard used a free TypeVar as its type argument, Pyrefly now correctly narrows to the TypeVar's bound.max/min key lambdas when default= is passed. Pyrefly was incorrectly typing the key callable‘s parameter from the expected type of the whole call rather than from the iterable’s element type.try/except, inference would degrade and report spurious errors.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.
pip install --upgrade pyrefly==1.4.0
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:
pyrefly check --suppress-errorspyrefly check --remove-unused-ignoresThis 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.
@stroxler, @rchen152, @kinto0, @connernilsen, generatedunixname2066905484085733, @asukaminato0721, @jakevdp, @samwgoldman, @grievejia, @ndmitchell, David Tolnay, generatedunixname1699489071355949, @yeetypete, @QEDady, @javabster, @shahhamdihassan, @manmartgarc, @DetachHead, @yangdanny97, @alexander-beedie, generatedunixname89002005307016, @gaborv, @MarcoGorelli, @tonyyuyiding, @nitishagar, @vgvr0, @tobyh-canva, Catherine Gasnier, @stepanhruda, @pavelzw, @hrolfurgylfa, @NathanTempest, @oprypin, @arthaud, @akhil9tiet, @Aayushyaash, @savagecx, @n-gao, @dedsec-terminal, @Vishwaspatel2401, Willem Kokke, @Aniketsy, @Pager-dot, Alan Kurusingal, @digvijaysai29, @igorsugak, @shobhitmehro, @Trighap52, @maggiemoss, @dantrapp, @fineguy, @itamaro, @danielpassy, @aodihis, @kain88-de, Boyan Atanasov, @Parzivalart3mis, @cweider, @eriksimonson, @Divyansh151005, @iamhaseebn, @nikhil-CLTI, @WilliamK112, @nikmos3, @Wilfred, @kevin9327
Please note: These release notes summarize major updates and features. For brevity, not all individual commits are listed.