Nuitka Python Compiler

4.0.8 · active · verified Sat Apr 11

Nuitka is a Python compiler that transforms Python scripts and modules into optimized C code, which is then compiled into standalone executables or extension modules. It aims to improve execution performance, offer better source code obfuscation, and simplify application distribution by bundling all dependencies. Compatible with CPython versions 2.6, 2.7, and 3.4-3.13, it supports Windows, macOS, and Linux. The current stable version is 4.0.8, with an active development cadence including frequent updates and new major releases.

Warnings

gotcha Nuitka requires a compatible C compiler to be installed and correctly configured on your system (e.g., Visual Studio/MinGW-w64 on Windows, GCC/Clang on Linux/macOS). Missing or misconfigured compilers are a common initial setup hurdle.
Fix: Ensure a supported C compiler is installed and accessible in your system's PATH. Nuitka may offer to download one on Windows. For detailed setup, consult the Nuitka documentation.
gotcha When compiling in `--standalone` or `--onefile` mode, Nuitka might not automatically detect all data files (e.g., configuration files, images, model files) used by your application. This can lead to `FileNotFoundError` at runtime.
Fix: Manually include necessary data files or directories using `--include-data-files=<source_path>=<destination_path>` or `--include-data-dir=<source_dir>=<destination_dir>` options during compilation.
gotcha The `--onefile` option, while convenient, can be more complex to debug for missing files and may result in slower startup times due to the unpacking process. `--standalone` (which creates a distribution folder) is generally recommended for initial testing and debugging.
Fix: Start with `--standalone` to ensure your application works correctly, then switch to `--onefile` once all dependencies and data files are correctly handled and you are comfortable with the trade-offs.
gotcha Always invoke Nuitka using `python -m nuitka` instead of just `nuitka`. This ensures Nuitka runs with the specific Python interpreter you intend, preventing issues like `SyntaxError` or `ImportError` if multiple Python versions are present on your system.
Fix: Replace `nuitka your_script.py` with `python -m nuitka your_script.py` in your build commands.
gotcha Nuitka can compile Python modules into CPython extension modules, but these cannot be directly executed using `python -m <compiled_module_name>`. Python's `-m` flag expects source code or a specific module structure that compiled extensions do not provide.
Fix: Import the compiled extension module into another Python script and call its functions (e.g., `import compiled_module; compiled_module.main()`) or wrap it with a small executable script.
gotcha Compiled Nuitka programs are designed to be stable, but segfaults or unexpected crashes can sometimes occur due to Nuitka bugs, unusual runtime conditions, or issues within third-party C/C++ extension modules.
Fix: If a compiled program crashes, recompile it with the `--debug` flag. This adds runtime checks and often transforms a segfault into a more informative assertion error, aiding in diagnosis. Additionally, check for missing data files or implicit imports.

Install

pip install Nuitka Install Nuitka

Imports

Nuitka via command line
```
python -m nuitka your_script.py
```
Nuitka is primarily a command-line tool. Using 'python -m nuitka' ensures it runs with the intended Python interpreter.

Quickstart

Create a file named `hello.py` with the content above, then compile it into a standalone executable. Run the executable from the `hello.dist` directory.

print('Hello, Nuitka!')

view raw JSON →