Tool:Nuitka
| Developer | Kay Hayen and contributors |
|---|---|
| License | AGPL-3.0 with the Nuitka Runtime Library Exception at the cited commit (older releases: Apache-2.0, Unverified) |
| Website | https://nuitka.net |
| On this wiki | Facts · Code · Notes · Topics |
Python-to-C compiler whose executables contain no bytecode: modules become native code, and a --onefile build is a bootstrap executable with a KA-tagged, optionally zstd-compressed payload of files appended to it and an 8-byte payload size at the very end.
Recognizing Nuitka output
- Modules are compiled to C and linked into the program or into extension modules (
.pyd,.so): there are no.pycfiles or marshalled code objects to decompile. Python semantics survive as calls into CPython-API-compatible helper code (Nuitka_Function,Nuitka_Generatortypes), compiled-function objects, and attribute__compiled__on modules and functions, which only exists in Nuitka output (Fact:Nuitka/identification/Compiled functions expose compiled). - Standalone builds (
--standalone) are a folder with the exe,python3XX.dll/libpython, the stdlib as compiled modules or bytecode for modules left uncompiled, and data files. Constants are stored in a blob (symbolconstant_bin) linked as a COFF object on Windows, a Mach-O section on macOS and a C array elsewhere (see #Constants blob). - Environment variables
NUITKA_ONEFILE_PARENTandNUITKA_ONEFILE_DIRECTORYare used by onefile builds; they appear as strings in the bootstrap and the child.
Onefile payload
A --onefile executable is a small C bootstrap with the payload appended (or embedded as a constant blob on small builds). Appended payload layout (Fact:Nuitka/struct/Onefile payload):
| Part | Contents |
|---|---|
| tag | ASCII KA then one byte: X uncompressed, Y zstd-compressed (Format:Zstandard)
|
| records | per file: relative name (UTF-16LE with NUL on Windows, UTF-8 with NUL elsewhere); on non-Windows a flags byte (bit 0 executable, bit 1 symbolic link, followed by the link target string); uint64 file size; optional CRC-32 (uint32, 0 is never stored: value 1 replaces it); when each file is compressed separately, uint32 compressed size; then the data
|
| end | uint64 payload size in the 8 bytes at the very end of the file; the bootstrap locates the end of the PE image first (a PE may carry a signature)
|
The bootstrap unpacks into a temporary directory chosen from a spec like {TEMP}/onefile_{PID}_{TIME_US}_{RANDOM} (or a cached directory) and starts the real program from there. Extraction therefore only needs the layout above and zstd; the unpacked folder is a standalone distribution. Details vary with options (--onefile-no-compression, archive mode, checksum on/off): treat the record layout as Unverified for your version until a sample parses (Format:Zstandard).
Analysis
Work on the native code like any C program; Python-level names survive as strings (function and module names, constants) and as compiled-function tables. Unverified: whether Nuitka output can be mapped back to source with the constants blob and symbol names; no decompiler exists.
Constants blob
Nuitka does not keep Python code objects as pyc data; strings, numbers, tuples, dicts, names and similar constants of every compiled module are packed into one blob that the runtime decodes at start-up (Fact:Nuitka/struct/Constants blob container). The blob is a list of named sections (a NUL-terminated name, a 32-bit size, then tagged data); the loader special-cases a section named .bytecode. The .bytecode section holds the bytecode of modules left uncompiled: DataComposerInterface.py maps __bytecode.const to the name .bytecode, and the generated loader (CodeTemplatesLoader.py) calls loadConstantsBlob(tstate, bytecode_data, ".bytecode") for the meta-path loader. Inside a section every value starts with a tag byte, an ASCII letter such as T tuple, L list, D dict, n None, u/v/w text, b/c/d bytes, and lengths use a base-128 varint (Fact:Nuitka/magic/Constants blob tag bytes). Tags C, K, W and Y carry code-object descriptions (flag bits for qualname, free variables, generator kinds) from which the runtime builds code objects.
Use: to recover the names and string constants of a compiled program, locate constant_bin (a large data symbol or section) and decode it with the tag table. The stream is stored plain: DECODE(x) is defined as assert(x) in prelude.h unless _NUITKA_EXPERIMENTAL_WRITEABLE_CONSTANTS is set. The 32-bit section size is in native byte order (HelpersConstantsBlob.c unpackValueUint32 memcpy's it; DataComposer.py writes it with struct.pack("I"), native), so little-endian on x86 and ARM targets; the 16-bit count at the start of a section is native too (struct.pack("H")).
Code & repositories
- https://github.com/Nuitka/Nuitka @
999d9a7e11ad60eb14aea0e0b23932f92b2e73a3· license: Apache-2.0 (declared by the contributor for the files used; GitHub reports AGPL-3.0 for the repository)
Nuitka (Apache-2.0): onefile compressor and C bootstrap, runtime helpers for compiled modules.
Tested on: source read, not run: Read the source at this commit; not built or run. · checked 2026-10-18; last activity 2026-10-17
Evidence & references
- Nuitka/Nuitka commit 999d9a7e11ad60eb14aea0e0b23932f92b2e73a3 (Apache-2.0):
nuitka/tools/onefile_compressor/OnefileCompressor.pylines 60-200 and 300-370 (tag, per-file record),nuitka/build/static_src/OnefileBootstrap.clines 60-70, 180-280 (payload end, size at end, temp spec),CompiledCodeHelpers.clines 2000-2040.