15 Mai 2026
Nuitka Release 4.1
This is to inform you about the new stable release of Nuitka. It is the extremely compatible Python compiler, “download now”.
This release adds many new features and corrections with a focus on async code compatibility, missing generics features, and Python 3.14 compatibility and Python compilation scalability yet again. Python 3.14: Fix, decorators were breaking when disabling deferred annotations. (Fixed in 4.0.1 already.) Fix, nested loops could have wrong traces lead to mis-optimization. (Fixed in 4.0.1 already.) Plugins: Fix, run-time check of package configuration was incorrect. (Fixed in 4.0.1 already.) Compatibility: Fix, Distutils: Fix, incorrect UTF-8 decoding was used for TOML input file parsing. (Fixed in 4.0.1 already.) Fix, multiple hard value assignments could cause compile time crashes. (Fixed in 4.0.1 already.) Fix, string concatenation was not properly annotating exception exits. (Fixed in 4.0.2 already.) Windows: Fix, Python 3.14: Fix, there were various compatibility issues including dictionary watchers and inline values. (Fixed in 4.0.2 already.) Python 3.14: Fix, stack pointer initialization to Python 3.12+: Fix, generic type variable scoping in classes was incorrect. (Fixed in 4.0.2 already.) Python 3.12+: Fix, there were various issues with function generics. (Fixed in 4.0.2 already.) Python 3.8+: Fix, names in named expressions were not mangled. (Fixed in 4.0.2 already.) Plugins: Fix, module checksums were not robust against quoting style of module-name entry in YAML configurations. (Fixed in 4.0.2 already.) Plugins: Fix, doing imports in queried expressions caused corruption. (Fixed in 4.0.2 already.) UI: Fix, support for Compatibility: Fix, names assigned in assignment expressions were not mangled. (Fixed in 4.0.2 already.) Python 3.12+: Fix, there were still various issues with function generics. (Fixed in 4.0.3 already.) Clang: Fix, debug mode was disabled for clang generally, but only ClangCL and macOS Clang didn’t want it. (Fixed in 4.0.3 already.) Zig: Fix, macOS: Fix, yet another way self dependencies can look like, needed to have support added. (Fixed in 4.0.3 already.) Python 3.12+: Fix, generic types in classes had bugs with multiple type variables. (Fixed in 4.0.3 already.) Scons: Fix, repeated builds were not producing binary identical results. (Fixed in 4.0.3 already.) Scons: Fix, compiling with newer Python versions did not fall back to Zig when the developer prompt MSVC was unusable, and error reporting could crash. (Fixed in 4.0.4 already.) Zig: Fix, the workaround for Windows console mode Standalone: Fix, linking with Python Build Standalone failed because Python 3.6+: Fix, exceptions like Fix, not all ordered set modules accepted generators for update. (Fixed in 4.0.5 already.) Plugins: Disabled warning about rebuilding the Standalone: Filtered Debugging: Disabled unusable unicode consistency checks for Python versions 3.4 to 3.6. (Fixed in 4.0.5 already.) Python3.12+ Avoided cloning call nodes on class level which caused issues with generic functions in combination with decorators. (Added in 4.0.5 already.) Python 3.12+: Added support for generic type variables in UI: Fix, flushing outputs for prompts was not working in all cases when progress bars were enabled. (Fixed in 4.0.6 already.) UI: Fix, unused variable warnings were missing at C compile time when using Scons: Fix, forced stdout and stderr paths as a feature was broken. (Fixed in 4.0.6 already.) Fix, replacing a branch did not accurately track shared active variables causing optimization crashes. (Fixed in 4.0.7 already.) macOS: Fix, failed to remove extended attributes because files need to be made writable first. (Fixed in 4.0.7 already.) Fix, dict Python 3.13: Fix, the Python 3.11+: Fix, starred arguments were not working as type variables. (Fixed in 4.0.8 already.) Python2: Fix, Compatibility: Fix, loop ownership check in value traces was missing, causing issues with nested loops. Windows: Improved Python2: Fix, there was a compatibility issue where providing default values to the Windows: Fix, there were spurious issues with C23 embedding in 32-bit MinGW64 by switching to Plugins: Fix, the UI: Fix, listing package DLLs with UI: Fix, UI: Handled paths starting with Plugins: Followed multiprocessing Python 3.12+: Fix, generic class type parameters handling was incorrect. Python 3.12: Fix, deferred evaluation of type aliases was failing. Python 3.12+: Aligned Python 3.10+: Fix, uncompiled coroutine Python 3.13+: Fix, uncompiled coroutine macOS: Made finding Compatibility: Fix, class frames were not exposing frame locals. UI: Detected Distutils: Rejected macOS: Fix, Distutils: Fix, the wrong macOS: Fix, was attempting to change removed (rejected) DLLs, which of course failed and errored out. Python 3.14: Fix, tuple reuse was not fully compatible, potentially causing crashes due to outdated hash caches. Fix, fake modules were still being attempted to located when imported by other code, which could conflict with existing modules. Python 3.5+: Fix, failed to send uncompiled coroutines the sent in value in Fix, older Standalone: Fix, multiphase module extension modules with post-load code were not working properly. Fix, Avoid using the non-inline copy of Fix, loops could make releasing of previous values very unclear, causing optimization errors. Fix, Python 3.4 to 3.6: Fix, bytecode demotion was not working properly for these versions, also bytecode only files not working. Plugins: Added a check for the broken Android: Allowed Windows: Fix, the header path for self uninstalled Python was not detected correctly. Release: Fix, inclusion of the UI: Detected the OBS versions of SUSE Linux better. Suse: Allowed using Python 3.11: Fix, package and module dicts were not aligned close enough to avoid a CPython bug. Fix, unbound compiled methods could crash when called without an object passed. Standalone: Fix, multiphase module extension modules with postload. (Fixed in 4.0.8 already.) Onefile: Fix, while waiting for the child, it may already be terminated. macOS: Removed existing absolute rpaths for Homebrew and MacPorts. Python 3.14: Avoided warning in CPython headers. Python 3.14: Followed allocator changes more closely. Compatibility: Avoided using No-GIL: Applied some bug fixes to get basic things to work. Standalone: Add support for newer Standalone: Add workaround for refcount checks of Standalone: Add support for newer Standalone: Add support for newer Plugins: Revert accidental Standalone: Added missing DLLs for Enhanced the package configuration YAML schema by adding the Standalone: Fix, Standalone: Added support for the Standalone: Added data files for the Standalone: Added support for Standalone: Added support for the Anaconda: Fix, dependencies for the Plugins: Enhanced the auto-icon hack in PySide6 to use compatible class names. Standalone: Fix, Qt libraries were duplicated with Plugins: Fix, automatic detection of Anaconda: Fix, Plugins: Fix, our protection workaround could confuse methods used with UI: Added the UI: Add message to inform users about UI: Add support for Onefile: Allow extra includes as well. (Added in 4.0.2 already.) UI: Add Scons: Added new option to select Python 3.10+: Added support for Plugins: Added support for the multiprocessing Reports: Added structured resource usage ( Reports: Included individual module-level C compiler caching ( Added support for detecting and correctly resolving the Python prefix for the macOS: Added support for UI: Added the Windows: Added support for Windows: Added support for resources names as not just integers, important when we copy them from template files. MacPorts: Added basic support for this Python flavor. More work will be needed to get it to work fully though. Avoid including Linux: Cached the UI: Output a warning for modules that remain unfinished after the third optimization pass. Added an extra micro pass trigger when new variables are introduced or variable usage changes severely, ensuring optimizations are fully propagated, avoiding unnecessary extra full passes. Provided scripts to compile Python statically with PGO tailored for Nuitka on Linux, Windows, and macOS. Added support for running the Data Composer tool from a compiled Nuitka binary without spawning an uncompiled Python process. Enhanced the usage of Cached frequently used declarations for top-level variables to speed up C code generation. Sped up trace collection merging by avoiding unnecessary set creation and using a set instead of a list for escaped traces. Optimized plugin hook execution by tracking overloaded methods and added an option to show plugin usage statistics. Improved performance of module location by avoiding unnecessary module name reconstruction and redundant filesystem checks for pre-loaded packages. Improved the caching of distribution name lookups to effectively avoid repeated IO operations across all package types. Plugins: Cached callback plugin dispatch for Python 3.13: Handled sub-packages of Handled hard attributes through merge traces as well. Made constant blobs more compact by avoiding repeated identifiers and unnecessary fields. Enhanced Python compilation scripts further. (Fixed in 4.0.8 already.) Recognized late incomplete variables better. (Fixed in 4.0.8 already.) Made constant blobs more compact. (Fixed in 4.0.8 already.) Optimized calls with only constant keywords and variable posargs too. Fix, memory bloat occurred when C compiling Avoid using Avoided using Avoided inclusion of Avoided including UI: Relocated the warning about the available source code of extension modules to be evaluated at a more appropriate time. Debian: Remove recommendation for Debian: Used Debugging: Removed Python 3.11+ restriction for Removed no longer useful inline copy of Release: Added missing package to the CI container for building Nuitka Debian packages. Developer: Updated AI instructions for creating Minimal Reproducible Examples (MRE) to skip unneeded C compilation. Debugging: Added an internal function for checking if a string is a valid Python identifier. AI: Added a task in Visual Studio Code to export the currently selected Python interpreter path to a file, making it available as “python” and “pip” matching the selected interpreter. This makes it easier to use a specific version with no instructions needed. AI: Updated the rules to instruct AI to only generate useful comments that add context not present in the code. Containers: Added template rendering support for Jinja2 ( Projects: Clarified the current status and rationale of Python 2.6 support in the developer manual. Debugging: Added experimental flag Visual Code: Added integration scripts for RPM: Included the Python compile script for Linux. RPM: Removed the requirement for Install only necessary build tools for test cases. Avoided spurious failures in reference counting tests due to Python internal caching differences. (Fixed in 4.0.3 already.) Fix, the parsing of the compilation report for reflected tests was incorrect. Python 3.14: Ignored a syntax error message change. Python 3.14: Added test execution support options to the main test runner to use this version as well. Fix, the runner binary path was mishandled for the third pass of reflected compilations. Removed the usage of obsolete plugins in reflected compilation tests. Debugging: Prevented boolean testing of Added the Fix, newline handling in diff outputs from the output comparison tool was incorrect. Covered Prevented the program test suite from running an unnecessary variant to save execution time. macOS: Ignored differences from GUI framework error traces in headless runs in output comparisons. Reflected test for Nuitka, where it compiles itself and compares its operation has been restored to functional state. Used the new method to clear internal caches if available for reference counts. Disabled running nested loops test with Python 2.6. Containers: Detected Python 2 defaulting containers in Podman tooling. UI: Fix, there was a double space in the Windows Runtime DLLs inclusion message. (Fixed in 4.0.1 already.) Onefile: Separated files and defines for extra includes for onefile boot and Python build. Scons: Provided nicer errors in case of “unset” variables being used, so we can tell it. Refactored the process execution results to correctly utilize our Quality: Enabled automatic conversion of em-dashes and en-dashes in code comments to the autoformat tool. AI won’t stop producing them and they can cause Ensured that cloned outline nodes are assigned their correct names immediately upon creation, that avoids inconsistencies during their creation. Quality: Updated to the latest versions of Quality: Modified the PyLint wrapper to exit gracefully instead of raising an error when no matching files require checking. Quality: Avoided checking YAML package configuration files twice, since autoformat already handles them. Quality: Ensured that YAML package configuration checks output the original filename instead of the temporary one when a failure occurs. Quality: Prevented pushing of tags from triggering git pre-push quality checks. Quality: Silenced the output of Visual Code: Added the generated Python alias path file to the ignore list. Quality: Enabled auto-formatting for the Nuitka devcontainer configuration file. Watch: Avoided absolute paths in compilation to make reports more comparable across machines. Quality: Changed Scons: Disabled format security errors in debug mode and moved Python-related warning disables into common build setup code. Quality: Updated to the latest Scons: Avoided MSVC telemetry since it can produce outputs that break CI. Debugging: Enhanced non-deployment handler for importing excluded modules. Split import module finding functionality into more pieces for enhanced readability. Debugging: Added more assertions for constants loading and checking. macOS: Dropped the Debugging: Added more traces for deep hash verification. This release builds on the scalability improvements established in 4.0, with enhanced Python 3.14 support, expanded package compatibility, and significant optimization work. The Python 3.14 support remains experimental, but only barely made the cut, and probably will get there in hotfixes. Some of the corrections came in so late before the release, that it was just not possible to feel good about declaring it fully supported just yet.Bug Fixes
__builtins__ lacked necessary compatibility in compiled functions. (Fixed in 4.0.1 already.)--verbose-output and --show-modules-output did not work with forward slashes. (Fixed in 4.0.2 already.)localsplus was incorrect to avoid garbage collection issues. (Fixed in 4.0.2 already.)uv_build in the --project option was broken. (Fixed in 4.0.2 already.)--windows-console-mode=attach|disable was not working when using Zig. (Fixed in 4.0.3 already.)attach or disable was incorrectly applied on non-Windows platforms. (Fixed in 4.0.4 already.)libHacl_Hash_SHA2 was not filtered out unconditionally. (Fixed in 4.0.4 already.)CancelledError thrown into an async generator awaiting an inner awaitable could be swallowed, causing crashes. (Fixed in 4.0.4 already.)pytokens extension module. (Fixed in 4.0.5 already.)libHacl_Hash_SHA2 from link libs unconditionally. (Fixed in 4.0.5 already.)async def functions. (Added in 4.0.5 already.)zig as a C compiler. (Fixed in 4.0.6 already.)pop and setdefault using with := rewrites lacked exception-exit annotations for un-hashable keys. (Fixed in 4.0.8 already.)__parameters__ attribute of generic classes was not working. (Fixed in 4.0.8 already.)FileNotFoundError compatibility fallback handling was not working properly. (Fixed in 4.0.8 already.)--windows-console-mode=attach to properly handle console handles, enabling cases like os.system to work nicely.mkdtemp function was failing.coff_obj resource mode for it as well.post-import-code execution could fail because the triggering sub-package was not yet available in sys.modules.--list-package-dlls was broken due to recent plugin lifecycle changes.--list-package-exe was not working properly on non-Windows platforms failing to detect executable files correctly.{PROGRAM_DIR} the same as a relative path when parsing the --onefile-tempdir-spec option.forkserver changes for newer Python versions.sum built-in float summation with CPython’s compensated sum for better accuracy.throw() return handling was incorrect, restoring completed coroutine results via StopIteration.value rather than exposing them as ordinary return values to the outer await chain.cancel()/await suspension handling was incorrect, improved to ensure integration compatibility.create-dmg more robustly by also checking the Homebrew path for Intel and from PATH properly.static-libpython problems, which affected some forms of Anaconda.--project mixed with --main arguments as it is not useful.zig from PATH or from ziglang was not being used.module-root config value was being checked for uv build backend.yield from.gcc compilers lacking newer intrinsic methods had compilation issues that needed to be addressed.pkg_resources with the inline copy of Jinja2. These could mismatch and cause errors.incbin resource mode was not working with old gcc C++ fallback.patchelf versions 0.10 and 0.11 to prevent breaking Qt plugins.patchelf version 0.18 on Android.pkg_resources inline copy for Python 2 to source distributions was missing.patchelf 0.18.0 there too.pkg_resources for Jinja2 template location for loading.Package Support
paddle version. (Added in 4.0.1 already.)pandas. (Fixed in 4.0.1 already.)h5py version. (Added in 4.0.2 already.)scipy package. (Added in 4.0.2 already.)os.getenv over os.environ.get changes in anti-bloat configurations that stopped them from working. Affected packages are networkx, persistent, and tensorflow. (Fixed in 4.0.5 already.)openvino. (Added in 4.0.7 already.)relative_to parameter for from_filenames DLL specification, avoiding error-prone purely relative paths.flet_desktop app assets were missing, now preserving the packaged runtime and sidecar DLLs.tyro package.perfetto package.anyio process forking.plotly.graph package.numpy conda package on Windows were incorrect.PySide6 WebEngine framework support on macOS.mypyc runtime dependencies was including all top level modules of the containing package by accident. (Fixed in 4.0.5 already.)delvewheel plugin was not working with Python 3.8+. This enhances compatibility with installed PyPI packages that use it for their DLLs. (Fixed in 4.0.6 already.)PySide6.New Features
--recommended-python-version option to display recommended Python versions for supported, working, or commercial usage.Nuitka[onefile] if compression is not installed. (Added in 4.0.1 already.)uv_build in the --project option. (Added in 4.0.1 already.)nuitka-project-set feature to define project variables, checking for collisions with reserved runtime variables. (Added in 4.0.2 already.)--reproducible builds or not. (Added in 4.0.6 already.)importlib.metadata.package_distributions(). (Added in 4.0.8 already.)forkserver context. (Added in 4.0.8 already, for 4.1 Python 3.6 and earlier, as well as 3.14 support were added too.)rusage) performance information to compilation reports.ccache/clcache) statistics in compilation reports.PyEnv on Homebrew Python flavor.rusage information for Scons.__compiled__.extension_filename attribute to give the real filename of the containing extension module.--clang or ARM. (Added in 4.0.8 already.)Optimization
importlib._bootstrap and importlib._bootstrap_external. (Added in 4.0.1 already.)syscall used for time keeping during compilation to avoid loading libc for each trace. (Added in 4.0.8 already.)vectorcall for PyCFunction objects by directly checking for its presence instead of relying purely on flags, allowing more frequent use of this faster execution path.onFunctionBodyParsing and onClassBodyParsing to skip argument computation when no plugin overrides them.pathlib as hard modules.Anti-Bloat
sqlalchemy. (Fixed in 4.0.2 already.)pydoc in PySimpleGUI. (Added in 4.0.2 already.)doctest from zodbpickle. (Added in 4.0.5 already.)cython when using pyav. (Added in 4.0.7 already.)typing_extensions when using numpy. (Added in 4.0.7 already.)Organizational
libfuse2 package as it is no longer useful.platformdirs instead of appdirs.clang-format as it is available everywhere, even Python 2.7, and we still want nicely formatted code when we read things. (Added in 4.0.6 already.)wax_off. We have our own stubs generator project..j2) container files in our internal Podman tools.--experimental=ignore-extra-micro-pass to allow ignoring extra micro pass detection.bash and zsh autocompletion of Nuitka CLI options. These are now also integrated into Visual Studio Code terminal profiles and the Debian package.distutils in the spec.Tests
namedtuples to avoid unexpected bugs.Test suffix to syntax test files and disabled “python” mode and spell checking for them to resolve issues reported in IDEs.post-import-code functionality with a new subpackage test case.Cleanups
namedtuples variant, that makes it easier to understand what code does with the results.SyntaxError for older Python versions, nor is unnecessarily using UTF-8 welcome.black and adopted a faster isort execution by caching results.optipng and jpegoptim during image optimization auto-formatting.mdformat checks to run only once and silently.deepdiff version.universal target arch.Summary
--project option seems usable now.