16 March 2026
Nuitka Release 4.0
This is to inform you about the new stable release of Nuitka. It is the extremely compatible Python compiler, “download now”.
This release is a major release with many new features and the long wanted improvements for scalability of the Python compilation. Accelerated: The enhanced detection for uninstalled Anaconda and WinPython was not fully working. (Fixed in 2.8.1 already.) Onefile: Fixed an issue in DLL mode where signal handlers were not being registered, which could prevent proper program termination on signals like CTRL-C. (Fixed in 2.8.1 already.) Windows: Fixed incorrect handling of forward slashes in cache directory paths, which caused issues with Nuitka-Action. (Fixed in 2.8.1 already.) UI: The UI: The Onefile: On Windows, fixed a crash when using macOS: Fixed a crash that could occur when many package-specific directories were used, which could lead to the Standalone: For the “Python Build Standalone” flavor, ensured that debug builds correctly recognize all their specific built-in modules, preventing potential errors. (Fixed in 2.8.4 already.) macOS: Fixed an issue where macOS: Fixed an issue to ensure the system Otherwise, using UI: Fixed a misleading typo in the rejection message for unsupported Python 3.13.4. (Fixed in 2.8.5 already.) Accelerated: The runner scripts Plugins: Ensured that plugins detected by namespace usage are also activated in module mode. (Fixed in 2.8.5 already.) Standalone: Fixed an issue where non-existent packages listed in Standalone: Corrected the classification of the Windows: Ensured that temporary link libraries and export files created during compilation are properly deleted, preventing them from being included in the standalone distribution. (Fixed in 2.8.6 already.) Python3.14: Adapted to core changes by no longer inlining Python 3.14: Follow allocator changes and immortal flags changes. Python 3.14: Follow GC changes for compiled frames as well. Python 3.14: Catch attempts to clear a compiled suspended frame object. Fixed a potential mis-optimization for uses of Module: Fixed Reports: Fixed a crash when creating the compilation report before the source directory is created. (Fixed in 2.8.7 already.) Standalone: Fixed ignoring of non-existent packages from UI: The UI: Fixed an exception in the Windows: Fixed incorrect Python3.14: Added missing implicit dependency for Python3.13+: Fixed missing export of Python3.14: Adapted to change in evaluation order of Multiprocessing: Fixed issue where Scons: Fixed an issue where Zig was not used as a fallback when MinGW64 was present but unusable. Windows: Made onefile binary work on systems without runtime DLLs installed as well. Scons: Made tracing robust against threaded outputs. Python3.12+: Enhanced workaround for loading of extension modules with sub-packages to cover more cases. Scons: Fixed missing Zig version output. Scons: Fixed Zig detection to enforce PATH or CC usage on macOS instead of download, since it’s not available. UI: Fixed normalization of user paths, improving macOS support for reporting. Linux: Fixed the workaround for the Linux: More robust fallback to Compatibility: Fixed a bug where macOS: Fixed an issue where UI: Ensured tracing uses at least 80 characters for very narrow terminals to maintain readability. Compatibility: Fixed an issue where nested loops could have incorrect traces, potentially leading to mis-optimizations. Linux: Fixed an issue where Scons: Improved passed variables handling by detecting Fixed a bug where propagating class dictionaries needed extra micro passes to ensure proper optimization of their traces for the new variables. Scons: Fixed an issue with process spawning when using Scons: Followed the file closing behavior of the standard communicate closer to avoid potential hangs. Anti-Bloat: Avoided a warning during program shutdown when using a compiled Standalone: Added support for the macOS: Added support for newer Standalone: Added support for including more metadata for the Standalone: Metadata from Nuitka Package Configuration is now only included if the corresponding package is part of the compilation. (Fixed in 2.8.5 already.) Standalone: Added support for the Standalone: Added support for newer versions of the Standalone: Added support for the Standalone: Added support for Standalone: Added automatic detection of Standalone: Added support for the newer Standalone: Added support for the Standalone: Added support for newer UI: Added support for With this, you can simply run Previously Nuitka could only be used for building wheels with The Zig: Added experimental support for using Zig project’s Reports: Started capturing Only POSIX-compliant OSes will do it (Linux, macOS, and all BSD variants), but Android does not. Not yet part of the actual report, as we need to figure out how to use and present the information. Scons: Added experimental support for enabling Thin LTO with the Clang compiler. Standalone: Honor This allows users to manually reduce standard library usage, but it can also cause crashes from extension modules not prepared for the absence of standard library modules. Onefile: Allowed disabling the onefile timeout and hard killing on CTRL-C entirely by providing Scons: Added newer inline copy of Scons which supports Visual Studio 2026. (Added in 2.8.7 already.) Scons: Allowed using Python versions only partially supported for Nuitka with Scons. (Added in 2.8.7 already.) UI: Added option Reports: Including CPU instr and cycle counters in timing on native Linux. With appropriate configuration on Linux this allows to get at very precise timing configuration so we can judge even small compile time improvements correctly. We then don’t need many runs to average out noise from other effects. Don’t use wall clock but process time for steps that are not doing IO like module optimization for more accurate values otherwise, it is however not very accurate still. Python3.12+: Added support for function type syntax (generics). Python3.14: Added groundwork for deferred evaluation of function annotations. Python3.14: Added support for uncompiled generator integration which is crucial for Debugging: Added Windows: Added Python 3.14: Added experimental support for deferred annotations. Plugins: Added option DLLs: Added support for DLL tags to potentially control inclusion with more granularity. macOS: Added support for many more protected resource entitlements (Siri, Bluetooth, HomeKit, etc.) to the bundle details. Python: Added support for UI: Added support for merging user and standard YAML Nuitka package configurations, currently only including proper merging of implicit imports. Avoid making duplicate hard imports by dropping assignments if the variable was already assigned to the same value. Found previous assignment traces faster. The assignment and For matching unescaped traces we will do similar, but it’s not really used right now, so make it only a TODO as that will eventually be very similar. Also speeds up the first micro pass even more, because it doesn’t have to search and do other things. If no previous trace exists, none is attempted to be used. Also the common check if no by-name uses or merges of a value occurred was always used inverted and now should be slightly faster to use and allow to short-circuit. While this accelerated the first micro pass by a lot for per-assignment work, it mainly means to cleanup the design such that traces are easier to re-recognize. And this is a first step with immediate impacts. Much faster Python passes. The “Escape” and “Unknown” traces now have their own number spaces. This allows doing some quick checks for a trace without using the actual object, but just its number. Narrow the scope of variables to the outline scope that uses them, so that they don’t need to be dealt with in merging later code where they don’t ever change anymore and are not used at all. When checking for unused variables, do not ask the trace collection to filter its traces. Instead it works off the ones attached to the variable already. This avoids a lot of searching work. It also uses a method to decide if a trace constitutes usage rather than a long Faster variable trace maintenance. We now trace variables in trace collection as a dictionary per variable with a dictionary of the versions, this is closer to our frequent usage per variable. That makes it a lot easier to update variables after the tracing is finished to know their users and writers. Requires a lot less work, but also makes work less memory local such that the performance gain is relatively small despite less work being done. It also avoids having to maintain a per-variable set for its using scopes. Decide presence of writing traces for parameter variables faster. Avoid unnecessary micro passes. Detect variable references discarded sooner for better micro-pass efficiency. We were spending an extra pass on the whole module to stabilize the variable usage, which can end up being a lot of work. After a module optimization pass found no changes, we no longer make an extra micro pass to avoid stabilization bugs, but only check against it not happening in debug mode. Depending on the number of micro passes, this can be a relatively high performance gain. For the For “PASS 1” of Faster code generation. Indentation in generated C code is no longer performed to speed up code generation. To restore readability, use the new option Recognized module variable usages inside outlined functions that are in a loop, which improves the effectiveness of caching at run-time. (Added in 2.8.6 already.) Standalone: Partially solved a TODO of minimizing intermediate directories in r-paths of ELF platforms, by only putting them there if the directory they point to will contain DLLs or binaries. This removes unused elements and reduces r-path size. Windows: Made the caching of external paths effective, which significantly speeds up DLL resolution in subsequent compilations. (Fixed in 2.8.6 already.) macOS: Removed extended attributes from data files as well, improving performance. (Fixed in 2.8.7 already.) Scons: Stopped detecting installed MinGW to avoid overhead as it is not supported. (Fixed in 2.8.9 already.) Scons: Added caching for MSVC information to reduce compilation time and if already available, use that to detect Windows SDK location rather that using Avoid computing large Avoid including Fixed un-hashable dictionary keys not being properly optimized, forcing runtime handling. Avoid including Avoid including Added configuration to avoid compiled via C for large generated files for the UI: Don’t say It actually has worked for a while, and we since renamed that option, but the help still said it wouldn’t work in standalone mode. Debugging: Added assertions for code object creation. We were getting assertions from Python when built with Zig, and these are supposed to provide those as well. Debugging: In case of tool commands failing, output the too long command line if that was the error given. Anti-Bloat: Don’t allow custom UI: The help text for Release: Use lowercase names for source archives in PyPI uploads. (Fixed in 2.8.7 already.) Quality: Fixed an issue where “assume yes” was not being passed for downloads in the commit hook. UI: Improved wording for missing C compiler message. Debugging: More clear verbose trace for dropped expressions. Debugging: Output what module had extra changes during debug extra micro pass. Quality: Manage more development tools ( AI: Enhanced pull request template with directions for AI-driven PRs. AI: Added agent command User Manual: Added documentation about redistribution requirements for Python 3.12-3.14. Quality: Added Scons: Improved error message to point to Zig support if no C compiler is found. MonolithPy: Follow rename of our Python fork to MonolithPy to avoid confusion with the Nuitka compiler project itself. Scons: Prefer English output and warn user for missing English language pack with MSVC in case or outputs being made. UI: When running non-interactively, print the default response that is assumed for user queries to stdout as well, so it becomes visible in the logs. UI: Warn when using protected resources options without standalone/bundle mode enabled on macOS. Reports: Sort DLLs and entry points in compilation reports by destination path for deterministic output. Quality: Skip files with Release: Avoid compiling bytecode for inline copies that are not compatible with the running Python version during install. Visual Studio: Ignored names in backticks and code blocks in ReST for spelling checks. Actions: Ensured compilation reports are always recorded, even in case of errors, as they are most useful then. AI: Added a workflow AI: Added a workflow AI: Added further strategies for Minimal Reproducible Example (MRE) reduction to the agent workflow. UI: Reject input paths from standard library locations to prevent compiling files from there as main files. Added support for Also the tests specified can be a glob pattern, to match multiple tests, not just a test name. Added examples to the help output of the runner to guide the usage of the developers. Ignore multiline source code outputs of Python3.14 in tracebacks for output comparison, Nuitka won’t do those. Added test cases for poetry and distutils. Also verify that standalone mode works with Made the distutils tests cases much more consistent. Watch: Improved binary name detection from compilation reports for better mode support beyond standalone mode. Allow downloading tools (like Added options to enforce Zig or Clang usage for C compiling. Suppress Added Added colorization to test comparison diffs if a tty is available. Avoided using Moved options to new Python3.14: Fixed a type mismatch warning seen with MSVC. (Fixed in 2.8.9 already.) Massive amounts of spelling cleanups. Correct spelling is more and more places allows identification of bugs more immediately, therefore these are very worthwhile. Code cleanup and style improvements in Replaced usages of Moved MSVC re-dist detection to Release: Don’t install UI: Tone down complaint about checksum mismatches. Static source files are now provided by Nuitka directly. Renamed C function This release is finally a break-through for scalability. We will continue the push for scalability in the next release as well, but with more of a focus on the C compilation step, to generate C code that is easier for the backend compiler. Also, this release finally addresses many usability problems. The non-deployment hooks for imports not found, that were actively excluded, are one such thing. The start of Other huge improvements are related to generics, they are now much better support, closing gaps in the Python3.12 support. The onefile DLL mode as used on Windows is finally perfect and should have no issues anymore, while enabling big future improvements. Unfortunately 3.14 support is not yet ready and will have to be delayed until the next release.Bug Fixes
--output-dir option was not being honored in accelerated mode when --output-filename was also provided. (Fixed in 2.8.2 already.)--output-filename option help said it wouldn’t work for standalone mode when in fact it did for a while already. (Fixed in 2.8.2 already.)--output-dir where it was checking for the wrong folder to exist. (Fixed in 2.8.2 already.)otool command line being too long. (Fixed in 2.8.2 already.)$ORIGIN r-paths were set but ended up unused, which in some cases caused errors by exhausting the header space and preventing the build entirely. (Fixed in 2.8.5 already.)xattr binary is used.arch -x86_64 python for compilation could fail when some packages are installed that provide xattr as well, because that might be an arm64 binary only and would not work. (Fixed in 2.8.5 already.).cmd or .sh now are also placed respecting the --output-filename and --output-dir options. (Fixed in 2.8.5 already.)top_level.txt files could cause errors during metadata collection. (Fixed in 2.8.6 already.)site module, which was previously treated as a standard library module in some cases. (Fixed in 2.8.6 already.)hacl code for this version. (Fixed in 2.8.6 already.)locals() when transforming the variable name reference call. (Fixed in 2.8.6 already.)pkgutil.iter_modules not working when loading a module into a namespace. (Fixed in 2.8.7 already.)top_level.txt for metadata. (Fixed in 2.8.7 already.)--no-progress-bar option was not disabling the Scons progress bars. (Fixed in 2.8.7 already.)tqdm progress bar during process shutdown. (Fixed in 2.8.7 already.)sys.executable value in onefile DLL mode. (Fixed in 2.8.9 already.)_ctypes on Windows. (Fixed in 2.8.9 already.)PyInterpreter_* API.__exit__ and __enter__.sys.argv was not yet corrected when argparse was used early in spawned processes.memset zero length warning, which was wrongly applied to Clang. Only GCC requires it, and Clang complained about it.g++ when gcc is too old for C11 support.del of a subscript could cause wrong runtime behavior due to missing control flow escape annotations for the subscript value itself and the index.Info.plist user-facing entitlements keys mapping to multiple internal entitlements were not handled correctly._XOPEN_SOURCE was mistakenly appended for Clang, causing warnings.None or invalid types earlier.rusage capture.Package Support
xgboost package. (Fixed in 2.8.1 already.)oracledb package. (Fixed in 2.8.2 already.)PySide6 versions. (Fixed in 2.8.4 already.)transformers package. (Fixed in 2.8.5 already.)win32ctypes package. (Fixed in 2.8.6 already.)dask package. (Fixed in 2.8.6 already.)dataparser package. (Added in 2.8.7 already.)puremagic, pygments.lexers and tomli in standalone mode.mypyc runtime dependencies, no need to manually configure that anymore. Also our configuration was often only correct for a single OS, and single upstream versions which is now fixed for packages having it before.av (PyAV) package version.sentry_sdk, jedi, parso, and line_profiler packages.pandas versions.New Features
--project parameter to build using configuration from pyproject.toml (e.g. Poetry, Setuptools).python -m nuitka --project --mode=onefile and it will use the pyproject.toml or setup.py/setup.cfg files to get the configuration and build the Nuitka binary.build package, and for building wheels that is still the best way.--project option is currently compatible with build and poetry and detects the used build system automatically.zig cc as a C compiler backend for Nuitka. This can be enabled by setting the CC environment variable to point to the zig or zig.exe executable.rusage for OSes that support it.--nofollow-import-to for stdlib modules as well.--onefile-child-grace-time=infinity.--devel-profile-compilation for compile time profiling. Also renamed the old runtime profiling option --profile to --debug-profile-runtime, that is however still broken.asyncio correctness and general usability with modern frameworks.--debug-self-forking to debug fork bombs.--include-windows-runtime-dlls option to control inclusion of Windows C runtime DLLs. Defaults to auto.--qt-debug-plugins for debugging Qt plugin loading.@nuitka_ignore decorator to exclude functions from compilation.@nuitka_ignore
def my_cpython_func():
# This function is not compiled, but stays bytecode
...
Optimization
del nodes were using functions to find what they already knew from the last micro pass. The self.variable_trace already kept track of the previous value trace situation.elif chain.telethon.tl.types module this was a 13% performance gain on top.telethon.tl.types, which has been one of the known troublemakers with many classes and type annotations, all changes combined improve the compilation time by 1500%.--devel-generate-readable-code which will use clang-format to format the C code.vswhere.exe each time.% string interpolations at compile time. These could cause constants to be included in the binary as a result.importlib._bootstrap and importlib._bootstrap_external as they are available as frozen modules.Anti-Bloat
tzdata on non-Windows platforms. (Fixed in 2.8.7 already.)pyparsing.testing in the pyparsing package.sqlfluff package.Organizational
--include-data-files-external doesn’t work in standalone mode.nofollow modes, point the user to the correct option instead. This was never needed, but two ways of providing this user decision make no sense.--include-data-files-external was updated to reflect that it works in standalone mode. (Fixed in 2.8.5 already.)clang-format, etc.) via private pip space for better consistency and isolation.create-mre to assist in creating a minimal reproduction example (MRE).--un-pushed argument to auto-format tool for checking only un-pushed changes.spell-checker: disable in codespell checks.create-mre to assist in creating a Minimal Reproducible Example from a larger file triggering a Nuitka bug. This has guidance on avoiding standalone mode and instructions for reducing code to just produce a MRE that is really small.fix-module-not-found-error for solving simple ModuleNotFoundError at runtime errors.Tests
--all with --max-failures option to the test runner to stop after a specified number of failures, or just run all tests and output the failed tests in the end.--project for the supported build systems.clang-format) for all test cases.pip output when not running interactively to avoid test output differences.nuitka.format and nuitka.package_config to self-compilation tests.--nofollow-imports in tests as some Python flavors do not work with it when using --mode=standalone.Cleanups
nuitka.options package.Errors and OutputDirectories modules.os.environ.get with os.getenv for consistency and denser code.DllDependenciesWin32.zstandard by default anymore.modulecode_ to module_code_ for consistency.Summary
--project enables far easier adoption of Nuitka for existing projects.