Nuitka: compiling Python to C and standing it up as an executable

What Nuitka is for, and who actually needs it

The README opens by calling Nuitka "the Python compiler" and describing it as a replacement or extension to the Python interpreter. That sentence is doing a lot of work, because it sets the expectation. Nuitka is not a second interpreter you write code against. It takes the modules you already have and translates them into a C level program that uses libpython plus static C files of its own, so the result executes the same way CPython does.

The audience follows from that. If you distribute a Python application to users who will not run pip, you need a binary, and Nuitka's standalone and onefile modes exist for exactly that. The README states that binaries become independent of the Python installation with --mode=standalone and --mode=onefile. If you maintain a library and want an extension module instead of a script, the same translation path produces one. If your goal is a faster Python, the README is explicit that all optimization is aimed at avoiding overhead where it is unnecessary, and that none is aimed at removing compatibility. That is a narrower promise than the word compiler usually implies.

The compatibility claim is the unusual part. The manual says Nuitka compiles every construct that Python 2 (2.6, 2.7) and Python 3 (3.4 through 3.14) have, when Nuitka itself runs under that same version. Uncompiled and compiled code then execute together. That is what makes it usable on real projects that mix pure Python with C extensions, rather than on a subset you have to refactor toward.

The translation path from module to C program

The mechanism, as the README describes it, is a source-to-C translation. Nuitka reads Python modules and emits a C level program. That program is not a fresh runtime: it uses libpython and a set of static C files that Nuitka ships, and it executes in the same way CPython does. Compatibility is the design constraint, not a side effect.

The build itself is orchestrated by Scons, which the README names as an internally used tool. That detail matters more than it looks. The manual warns that for Python 3.4 and only that version, you need a second Python (2.x, or 3.5 or higher) installed as a compile time dependency, because Scons does not support the same Python versions Nuitka does. Nuitka locates that second interpreter itself, for example through the Windows registry, so in practice you only notice if it is missing.

There is a similar pattern for optional features. The README notes that onefile compression works on Python 2.x when another Python is found that has the zstandard package installed. requirements.txt lists zstandard with the marker python_version >= '3.5' and python_version < '3.14', and notes that on Python 3.14 and above the stdlib compression.zstd is used instead. The dependency set is deliberately thin: appdirs, tqdm, subprocess32 on 2.7 only, zstandard, pyyaml and Jinja2 >= 2.10.2, with the comment that other than orderedset and zstandard these are not nearly required for installation but nice to have updated relative to the inline copies in Nuitka. Inline copies are a recurring theme in this codebase, and setup.py mentions avoiding byte code compilation for inline copies of scons with mismatching Python major versions.

One more architectural fact is easy to miss. The README says you need CPython, Anaconda Python or Homebrew Python to execute Nuitka, because it is closely tied to implementation details of CPython. Nuitka is not a PyPy tool.

Installing Nuitka and compiling a first script

Nuitka is distributed on PyPI, which is where the README's badge links point. Install it into the interpreter you intend to compile with, since the manual ties Nuitka's supported version to the Python that runs it. The README does not print an install command, so use the standard pip invocation for the PyPI project.

Before compiling anything, confirm a usable C compiler is on the machine. The README lists the accepted ones: the zig compiler via --zig, MinGW64 on Windows via --mingw64, Visual Studio 2022 or higher on Windows, gcc 5.1 or higher (or g++ 4.4 as an alternative) elsewhere, clang on macOS and most FreeBSD architectures, and clang-cl on Windows when the Visual Studio installer provides it. On Windows the README recommends letting Nuitka download MinGW64 automatically when no usable compiler is found, and says Nuitka will also upgrade it for you.

The README does not give a compile command line either. What it does document is the set of options that decide the output: the acceleration mode, which produces a binary next to your script, and the two modes that make the result independent of the Python installation. The README notes the suffix for acceleration mode is added so the original script name and the binary name never collide. To hand the result to someone who does not have Python installed, the README states that --mode=standalone makes the created binaries executable independent of the Python installation. If you want a single artifact rather than a directory, --mode=onefile is the other documented option, and it is the one that pulls in zstandard for compression on Python versions below 3.14. For a library rather than a program, the same translation path yields an extension module.

On naming: the README says binaries get an .exe suffix on Windows, and on other platforms no suffix in standalone mode or a .bin suffix that you are free to remove, change, or specify with -o. Expect a build that shells out to a C compiler and takes noticeably longer than a packaging step that only copies files.

Compiler and interpreter combinations that will not work

The requirements section is unusually blunt about exclusions, and they are the first thing to check before planning a build pipeline. Windows app store Python definitely does not work, and the README says it is checked against. macOS pyenv does not work either; the manual directs you to Homebrew instead for self compiled Python installations, while warning that standalone mode will be worse on these platforms and less backward compatible with older macOS versions.

Compiler choice has its own trap. MinGW64 does not work with Python 3.13 or higher, and the README adds that it must be the MinGW64 that Nuitka downloads, because there were frequent breakage with the complete tooling used. That is a real constraint if your organisation pins a system MinGW64. Windows builds also favour an English language pack for Visual Studio, since Nuitka filters away garbage outputs only for English.

Architecture mismatches produce cryptic errors rather than clear ones. The README says to make sure Python and the C compiler match architecture, or else you will get cryptic error messages. It also notes that the zig compiler on Windows is currently limited to compiling for x64 (AMD64) Python.

Finally, the C standard requirement is not universal. The README asks for a C11 compiler or a C++03 compiler as a fallback, and explains in a footnote that older MSVC compilers do not do C11, so with Python 3.10 or older the overlapping C++03 standard is used instead. If your toolchain is older than gcc 5.x or any clang, you are outside the supported set.

Nuitka against PyInstaller and Cython

The comparison people reach for most is PyInstaller, and the difference is at the level of what the tool produces. PyInstaller bundles an interpreter and your bytecode into an archive that unpacks at runtime. Nuitka translates your modules into C, compiles that C, and links libpython and its own static C files, per the README's description of the pipeline. The practical consequences run in both directions: Nuitka needs a working C compiler and a longer build, while a bundle that carries bytecode is a different proposition for anyone trying to read your source back out.

Cython sits closer to Nuitka in that both emit C, but the starting point differs. Cython is a superset language where you annotate types to get speed, and you generally rewrite the hot parts. Nuitka takes unmodified Python and is explicit that optimization targets overhead rather than compatibility, with a full compatibility mode to disable even improved error messages. If you want to keep your source as plain Python and still ship a binary, that is Nuitka's ground. If you want to hand-tune the C boundary, Cython gives you the controls.

The licence is a third axis. Nuitka is AGPL-3.0, with a separate LICENSE-RUNTIME.txt described in pyproject.toml as the "Nuitka Runtime Library Exception, Version 1.0" granting additional permissions under Section 7. PyInstaller and Cython are not AGPL. For a proprietary application, that exception file is the thing to read, not the headline licence name.

Licence terms and what a build pipeline has to carry

Nuitka is licensed under the GNU Affero General Public License, Version 3. The repository also ships LICENSE-RUNTIME.txt, and pyproject.toml points to it as the "Nuitka Runtime Library Exception, Version 1.0" that grants additional permissions under Section 7 of the AGPL. The existence of a runtime exception is the signal that compiled output is meant to be distributable on different terms than the compiler itself, but the scope of that exception is defined by the file, not by this summary. Anyone shipping a closed source binary should have the exception read by whoever handles licensing, because AGPL-3.0 without an applicable exception is a very different obligation.

Upgrade cost is mostly environmental. The supported Python range is wide (2.6, 2.7, and 3.4 through 3.14), which means a build machine can lag on Python for a long time. The pressure points are the compiler and the optional helpers. MinGW64 stops working at Python 3.13, so a Windows pipeline that relies on it has to move to a different compiler before that upgrade. The zstandard dependency disappears at Python 3.14 in favour of the stdlib compression.zstd, so that requirement changes shape on its own. requirements.txt keeps inline copies of several dependencies, which is why a stale environment can still build but with older vendored code paths.

The repository carries a Changelog.rst at the top level, and the default branch is develop, so the changelog is the place to check what a version bump changes before you take it.

Editorial conclusion

Adopt Nuitka if you ship a CPython program to machines without a Python installation and you can control the build machine's C compiler. Do not adopt it expecting a drop-in speedup, or if your target is Windows app store Python, macOS pyenv, or MinGW64 on Python 3.13 and above. Verify first that your interpreter is CPython, Anaconda or Homebrew Python, that gcc 5.1 or clang is present, and that your distribution obligations under AGPL-3.0 with the runtime exception are acceptable to whoever reviews licences.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Nuitka/Nuitka on GitHub
4. Project website
5. README