Status : BETA 🎉
Release date: 17 Nov 2025

🚀Pyrefly is now in Beta!

We’re thrilled to announce with this release that Pyrefly has transitioned from Alpha to Beta status! This marks a new chapter for the project, with increased stability, feature maturity, and readiness for broader adoption. When using a version of Pyrefly with Beta status you can feel confident that the IDE extension is ready for production use, while core type-checking features can be used, but be aware some edge cases are still being addressed as we make progress towards a later stable v1 release (bug reports welcome!).

These release notes will use a slightly different format than usual, covering the major highlights of the last 6 months that have contributed to this milestone.

🏆 Major Highlights from Alpha Releases

1. IDE & Language Server Features

• Instant IDE Startup: Major performance improvements for large environments.
• Semantic Highlighting, Inlay Hints: Enhanced code readability and added highlighting for unreachable blocks and unused function parameters. Unnecessary/obvious inlay hints are no longer displayed.
• Hover Cards & Docstrings: Richer information in tooltips, including docstrings for built-in types and links to error documentation.
• Configurable LSP Features: Greater control over enabling/disabling IDE features like autocomplete, go-to-definition, and hover.
• Extensions released for a range of popular IDEs, including VSCode, PyCharm and more!
• Some relevant issues: #853, #1403, #1335, #873, #802, #716

2. Type Checking Enhancements

• Improved overload evaluation: Fully compliant with the Python typing spec
• Smarter Type Narrowing: Improved handling of variable types in loops, control flow, and pattern matching. Added ability to understand patterns like `getattr()`, `hasattr()`, and `dict.get()`
• TypedDict & Protocol Improvements: More accurate type checking for structural types, including handling for union keys and improved inheritance checks.
• Additional Python typing features: LiteralString & TypeAliasType support, abstract class instantiation checks, unused awaitable checks, multiple inheritance consistency checks, and more!
• Configurable Type Inference: Advanced features like empty container inference and return type inference can be toggled via config.
• Some relevant issues: #684, #872, #1058, #940, #815, #1461, #44

3. Error Reporting & Suppression

• Granular Error Filtering: Filter summarized errors by code, set error severity, and get clickable links to docs.
• Suppression Workflow: Scripts and commands to silence new errors after upgrades, making large codebase migrations manageable.
• Improved Error Messages: Clearer, more actionable diagnostics for overloads, missing imports, and more.
• Some relevant issues: #1276, #1302, #890, #1401

4. Framework Integrations

• Django: Partial support, with ongoing improvements for model field inference, enum support, and lazy label handling.
• Pydantic: Experimental support, with growing documentation and bug fixes.
• Some relevant issues: #316, #334, #1276, #839

5. Jupyter Notebook Support (Experimental)

• Full Language Server Integration: Diagnostics, inlay hints, go-to-definition, hover, semantic tokens, signature help, and completions now work out-of-the-box for .ipynb files.
• CLI Type Checking for Notebooks
• Jupyter Lab Integration
• Some relevant issues: #381, #591, #1045, #1529, #925

6. Build Systems, Dependencies & Configuration

• Initial Build System Support: Foundational work for Buck and other build systems to support generated file materialization and source file remapping
• Editable Installs: Documentation and support for working with editable dependencies.
• Improved dependency handling: performance improvements and automatic recognition of third party libraries with typeshed stubs
• Some relevant issues: #573, #1, #2, #1239, #360

Check out the Pyrefly documentation for more details on how to use each of these features.

💡 What does Beta status mean for you?

The Beta release is your invitation to start using Pyrefly in real-world projects, provide feedback, and continue helping shape its future. You do not need to change how you install and upgrade Pyrefly now that we are in Beta status, the same semantic versioning format will remain in place.

You can continue providing feedback as usual by opening a GitHub issue or joining our Discord server. In this new phase of development as we push towards our next milestone (a stable v1.0 release) we are particularly interested in hearing about how you are using Pyrefly in real production environments, including any edge cases you may encounter.

📦 Upgrade

pip install --upgrade pyrefly==0.42.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 Pyefly documentation

📅What’s next?

Going forward we’ll be continuing development work the same as usual with weekly releases of new features and bug fixes. However we will be closing out our Beta milestone and moving on to the next - a stable V1 Release. We’ll be continuing to listen to your feedback and address open issues, so if there are specific things you want to see in a stable release, or blockers for adopting Pyrefly in your project - let us know!

🖊️ 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. Together we’ve closed almost 800 issues and made over 9,000 commits 😱 We want to sincerely thank everyone who has taken the time to make a contribution, large or small, and look forward to our continued collaboration on future releases.

@aahanaggarwal, @aaron-ang, @lolpack, @arosenber, @javabster, @abdallhfattah, Abel, @abhi-jha, @Adist319, Aditya Sinha, @Adamkaram, @ajaymiranda, @akmalsoliev, Alex, @Alex-Aron, @ahornby, Alexander Mols, Ali Tayyebi, @alokpr, @gvozdvmozgu, Anqi Wu, Arnav, @AryanBagade, @asukaminato0721, @krathul, Ben Carr, Brian Rosenfeld, @capickett, Carlos Fernandez, @charliecloudberry, @cclauss, @cjlongoria, @connernilsen, @cooperlees, Daniel Mueller, @yangdanny97, @darricklaidin, @dluo, @dtolnay, Dhruv Mongia, @kv9898, @diliop, @Dogacel, @ducdetronquito, Eric J Nguyen, @fangyi-zhou, @fatelei, @Zeko369, Grant Herman, @gvozdvmozgu, @hashiranhar, @fannheyward, @hugovk, @IDrokin117, @immanuel-peter, @InSyncWithFoo, @airvzxf, Ivan Loskutov, @jack-mcivor, @JakobDegen, @j-piasecki, @jagill, @jchanke, @grievejia, @jvansch1, @bigfootjon, Jun Hao, Kc Balusu, @CookieComputing, kitek, @krikera, @kshitijgetsac, @kinto0, Li Shen, lianne, LyricalToxic, @maggiemoss, @MarcoGorelli, @markmarkmarkthebest, @martindemello, @yamgent, @arthaud, @melvinhe, Miae Kim, @michaelcortese, Miyamoto Musashi, @mohesham88, @mrsobakin, Nathan Hawkes, @ndmitchell, @NSPC911, @oriori1703, Paul Iatchenii, @zpao, @pavelzw, @pawelstrzmeta, @prasannavenkateshgit, @pt2302, @rchen152, @regexyl, @ricardoleal20, @rchiodo, Ron Mordechai, @rubmary, @TheRustyPickle, @salvatorebenedetto, @samwgoldman, @SamChou19815, @sandeshbhusal, @sargun, @slawlor, @singiamtel, @stroxler, Takuma Iwaki, @Solumin, Thomas Polasek, @tianhan0, @Viicos, @VladimirMakaev, @WeixiMa, @Wilfred, Willy Lau, @xaskii, Xiaomin Liu, Yotam DK, @zachmullen, Zach Riser, @migeed-z, @LycheeBay, Zoltán Nagy, @zsol