Upcoming Release 4.2
Upcoming Release 4.2
This document outlines the changes for the upcoming Nuitka 4.2 release, serving as a draft changelog. It also includes details on hot-fixes applied to the current stable release, 4.1.
It currently covers changes up to version 4.1rc11. Note These are the draft release notes for the upcoming Nuitka 4.2 release. A primary goal for this version is to deliver significant enhancements in scalability. Development is ongoing, and this documentation might lag slightly behind the latest code changes. 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, 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 Plugins: Fixed automatic detection of 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 Anaconda: Fixed UI: Fixed flushing outputs for prompts was not working in all cases when progress bars were enabled. (Fixed in 4.0.6 already.) UI: Fixed missing unused variable warnings 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: Fixed failure to remove extended attributes because files need to be made writable first. (Fixed in 4.0.7 already.) Fix, dict Python 3.13: Fixed the Python 3.11+: Fixed starred arguments not working as type variables. (Fixed in 4.0.8 already.) Python2: Fixed Compatibility: Fix, loop ownership check in value traces was missing, causing issues with nested loops. Windows: Improved Python2: Fixed a compatibility issue where providing default values to the Windows: Fixed spurious issues with C23 embedding in 32-bit MinGW64 by switching to Plugins: Fixed an issue where the UI: Fixed an issue where listing package DLLs with UI: Fixed Windows: Fixed an issue where running batch files from within Nuitka could unintentionally execute system-wide auto-run scripts by explicitly disabling them in UI: Handled paths starting with Plugins: Enhanced the auto-icon hack in PySide6 to use compatible class names. Plugins: Followed multiprocessing Python 3.12+: Fixed generic class type parameters handling. Python 3.12: Fixed deferred evaluation of type aliases. Python 3.12+: Aligned Python 3.10+: Fixed uncompiled coroutine Python 3.13+: Fixed uncompiled coroutine macOS: Made finding Compatibility: Fixed class frames to expose frame locals as well. UI: Detected Distutils: Rejected macOS: Fixed to use Distutils: Fixed checking the wrong macOS: Fixed not attempting to change removed (rejected) DLLs. Distutils: Fixed improper handling of empty Python 3.14: Fixed an issue where tuple reuse was not fully compatible, potentially causing crashes due to outdated hash caches. Fixed fake modules still being located, which could conflict with existing modules. Python 3.5+: Fixed failure to send uncompiled coroutines the sent value in Fixed compilation issues with older Standalone: Fix, multiphase module extension modules with post-load code were not working properly. Fix, Avoid using the non-inline copy of Fixed loops making releasing of previous values very unclear, causing optimization errors. Fixed Standalone: Fixed duplicated Qt libraries with Python 3.13+: Fixed the need to check more flags for inline values. Python 3.4 to 3.6: Fixed bytecode demotion not working properly for these versions, also bytecode only files not working properly for importing scans. Plugins: Added a check for the broken Android: Allowed Windows: Fixed the header path for self uninstalled Python. Release: Fixed missing inclusion of the UI: Detected the OBS versions of SUSE Linux better. Suse: Allowed using Python 3.11: Fix, aligned package and module dicts closer to avoid a CPython bug. Plugins: Fix, our protection workaround could confuse methods used with 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: Fixed missing Standalone: Added support for the Standalone: Added data files for the Standalone: Added support for Standalone: Added support for the Anaconda: Fixed dependencies for the 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.) Fixed the parsing of the compilation report for reflected tests. 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. Fixed an issue where 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 Fixed newline handling in diff outputs from the output comparison tool. 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 is currently under active development and is not yet feature-complete.Nuitka Release 4.2 (Draft)
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.)mypyc runtime dependencies, was including all top level modules of the containing package by accident. (Fixed in 4.0.5 already.)async def functions. (Added in 4.0.5 already.)delvewheel plugin 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.)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. (Fixed in 4.0.8 already.)FileNotFoundError compatibility fallback handling. (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 so that it properly works on non-Windows platforms to detect executable files correctly.cmd.exe.{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 by restoring completed coroutine results via StopIteration.value rather than exposing them as ordinary return values to the outer await chain.cancel()/await suspension handling 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.module-root config value for uv build backend.module-root configuration.yield from.gcc compilers lacking newer intrinsic methods.pkg_resources with the inline copy of Jinja2. These could mismatch and cause errors.incbin resource mode not working with old gcc C++ fallback.PySide6 WebEngine framework support on macOS.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.patchelf 0.18.0 there too.PySide6.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 by preserving the packaged runtime and sidecar DLLs.tyro package.perfetto package.anyio process forking.plotly.graph package.numpy conda package on Windows.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