pyrefly

Full Changelog: https://github.com/meta/pyrefly/compare/1.4.0-dev.4...1.5.0-dev.1

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-attribute-access, 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 br

Full Changelog: https://github.com/facebook/pyrefly/compare/1.4.0-dev.3...1.4.0-dev.4

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 i