Nuitka

https://nuitka.net/user-documentation
Admin
Nuitka is a Python compiler that converts Python code into standalone executables or modules,...
Tokens:25,661
Snippets:244
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure setuptools for Nuitka

Source: https://nuitka.net/user-documentation/use-cases.html

Examples of passing Nuitka options within setup.py, including configurations for standalone and build-system compatible setups.

```python
# For setup.py if you don't use other build systems:
setup(
   # Data files are to be handled by setuptools and not Nuitka
   package_data={"some_package": ["some_file.txt"]},
   ...,
   # This is to pass Nuitka options.
   command_options={
      'nuitka': {
         # boolean option, e.g. if you cared for C compilation commands
         '--show-scons': True,
         # options without value, e.g. enforce using Clang
         '--clang': None,
         # options with single values, e.g. enable a plugin of Nuitka
         '--enable-plugin': "pyside2",
         # options with several values, e.g. avoid including modules
         '--nofollow-import-to' : ["*.tests", "*.distutils"],
      },
   },
)

# For setup.py with other build systems:
# The tuple nature of the arguments is required by the dark nature of
# "setuptools" and plugins to it, that insist on full compatibility,
# e.g. "setuptools_rust"

setup(
   # Data files are to be handled by setuptools and not Nuitka
   package_data={"some_package": ["some_file.txt"]},
   ...,
   # This is to pass Nuitka options.
   ...,
   command_options={
      'nuitka': {
         # boolean option, e.g. if you cared for C compilation commands
         '--show-scons': ("setup.py", True),
         # options without value, e.g. enforce using Clang
         '--clang': ("setup.py", None),
         # options with single values, e.g. enable a plugin of Nuitka
         '--enable-plugin': ("setup.py", "pyside2"),
         # options with several values, e.g. avoid including modules
         '--nofollow-import-to' : ("setup.py", ["*.tests", "*.distutils"]),
      }
   },
)
```

--------------------------------

### Example configuration for toga.platform

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

A configuration example demonstrating how to persist backend decisions by forcing a function to return a specific value.

```yaml
- module-name: 'toga.platform'
  variables:
    setup_code: 'import toga.platform'
    declarations:
      'toga_backend_module_name': 'toga.platform.get_platform_factory(). __name__'
  anti-bloat:
    - change_function:
        'get_platform_factory': "'importlib.import_module(%r)' % get_variable('toga_backend_module_name')"
```

--------------------------------

### Install Nuitka

Source: https://nuitka.net/user-documentation/tutorial-setup-and-build.html

Install Nuitka using pip and verify the installation.

```bash
python -m pip install Nuitka
```

```bash
python -m nuitka --version
```

--------------------------------

### Create Installers via CLI

Source: https://nuitka.net/user-documentation/use-cases.html

Commands to generate installers for Windows, macOS, and Linux using Nuitka's standalone mode.

```bash
python -m nuitka --mode=standalone --windows-create-installer program.py
python -m nuitka --mode=standalone --macos-create-installer program.py
python -m nuitka --mode=standalone --linux-create-installer program.py
```

--------------------------------

### Example expression

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

A simple expression combining OS and Python version checks.

```text
macos and python3_or_higher
```

--------------------------------

### Module Options Example for wx

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Ensures the wx toolkit is configured correctly for macOS by enforcing GUI mode and bundle requirements.

```yaml
- module-name: 'wx'
  options:
    checks:
      - description: 'wx will crash in console mode during startup'
        console: 'yes'
        when: 'macos'
      - description: 'wx requires program to be in bundle form'
        macos_bundle: 'yes'
        when: 'macos'
```

--------------------------------

### Verify Python Installation

Source: https://nuitka.net/user-documentation/tutorial-setup-and-build.html

Use this command to verify that Python is correctly installed and accessible in your environment.

```bash
python --version
```

--------------------------------

### Simple DLL Inclusion

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

A basic example of including a DLL with a known prefix from the package directory.

```yaml
- module-name: 'vosk'
  dlls:
    - from_filenames:
        prefixes:
          - 'libvosk'
```

--------------------------------

### Install ccache on macOS arm64

Source: https://nuitka.net/user-documentation/tips.html

Use Homebrew to install ccache on macOS arm64 systems to enable automatic compilation caching by Nuitka.

```bash
export HOMEBREW_INSTALL_FROM_API=1
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
eval $(/opt/homebrew/bin/brew shellenv)
brew install ccache

```

--------------------------------

### Tkinterweb Import Hack Example

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Demonstrates how to handle packages that modify sys.path at runtime by using global-sys-path.

```python
sys.path.append(os.path.dirname(os.path.realpath(__file__)))
```

```yaml
- module-name: 'tkinterweb'
  import-hacks:
    - global-sys-path:
        # This package forces itself into "sys.path" and expects absolute
        # imports to be available.
        - ''
```

--------------------------------

### Implicit Imports Example for cv2

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Configures environment variables for Qt plugins and fonts, and lists dependencies for the cv2 module.

```yaml
- module-name: 'cv2'
    - depends:
        - 'cv2.cv2'
        - 'numpy'
        - 'numpy.core'
    - pre-import-code:
        - |
          import os
          os.environ['QT_QPA_PLATFORM_PLUGIN_PATH'] = os.path.join(os.path.dirname(__file__), 'qt/plugins')
          os.environ['QT_QPA_FONTDIR'] = os.path.join(os.path.dirname(__file__), 'qt/fonts')
      when: 'linux and standalone'
```

--------------------------------

### GitHub Actions Workflow for Nuitka Builds

Source: https://nuitka.net/user-documentation/use-cases.html

An example workflow configuration for GitHub Actions that builds executables on macOS, Ubuntu, and Windows using Nuitka-Action.

```yaml
jobs:
build:
   strategy:
      matrix:
      os: [macos-latest, ubuntu-latest, windows-latest]

   runs-on: ${{ matrix.os }}

   steps:
      - name: Check-out repository
      uses: actions/checkout@v4

      - name: Setup Python
      uses: actions/setup-python@v5
      with:
         python-version: '3.10'
         cache: 'pip'
         cache-dependency-path: |
            **/requirements*.txt

      - name: Install your Dependencies
      run: |
         pip install -r requirements.txt -r requirements-dev.txt

      - name: Build Executable with Nuitka
      uses: Nuitka/Nuitka-Action@main
      with:
         nuitka-version: main
         script-name: your_main_program.py
         # many more Nuitka options available, see action doc, but it's best
         # to use nuitka-project: options in your code, so e.g. you can make
         # a difference for macOS and Linux, and create an app bundle there.
         mode: app

      - name: Upload Artifacts
      uses: actions/upload-artifact@v4
      with:
         name: ${{ runner.os }} Build
         path: | # match what's created for the 3 OSes
            build/*.exe
            build/*.bin
            build/*.app/**/*
         include-hidden-files: true
```

--------------------------------

### Conditional Deployment Mode via Project Options

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

Example of using Nuitka project options to conditionally enable deployment mode based on an environment variable.

```python
# nuitka-project-if: os.getenv("DEPLOYMENT") == "yes":
#  nuitka-project: --deployment
```

--------------------------------

### Anti-Bloat Configuration

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Example of using anti-bloat to remove dependencies or modify module code.

```yaml
anti-bloat:
  - description: 'remove tests'
    context: ''
    module_code: 'from hello import world'
    replacements_plain: ''
    replacements_re: ''
    replacements: ''
    change_function:
       'get_extension': 'un-callable'

    append_result: ''
    append_plain: ''
    when: ''
```

--------------------------------

### Configure torch package modules

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

This example demonstrates using constants to filter module candidates and variables to perform conditional imports based on those candidates.

```yaml
- module-name: 'torch.utils._config_module'
  constants:
    declarations:
      'torch_config_module_candidates': '[m for m in iterate_modules("torch")     if m.split(".")[-1] in ("config", "_config")]'
  variables:
    setup_code: 'import importlib'
    declarations:
      'torch_config_modules': 'dict((m,importlib.import_module(m).    _compile_ignored_keys) for m in torch_config_module_candidates if hasattr    (importlib.import_module(m), "_compile_ignored_keys"))'
```

--------------------------------

### Anti-bloat Configuration for imageio

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

A configuration snippet used to replace misleading pip install error messages with Nuitka-specific instructions for including modules.

```yaml
- module-name: 'imageio.core.imopen'
  anti-bloat:
    - replacements_plain:
        '`pip install imageio[{config.install_name}]` to install it': '`--include-module={config.module_name}` with Nuitka to include it'
        'err_type = ImportError': 'err_type = RuntimeError'
      when: 'not deployment'
```

--------------------------------

### Configure Nuitka Project Options with Conditionals

Source: https://nuitka.net/user-documentation/user-manual.html

Example of using conditional directives and dynamic variable setting within a source file to control compilation modes and metadata.

```python
# Compilation mode, support OS-specific options
# nuitka-project-if: {OS} in ("Windows", "Linux", "Darwin", "FreeBSD"):
#    nuitka-project: --mode=onefile
# nuitka-project-else:
#    nuitka-project: --mode=standalone

# Set variables dynamically and use them later, e.g., for Windows metadata
# nuitka-project-if: {OS} == "Windows":
#    nuitka-project-set: MY_VERSION = __import__("mypkg").__version__
#    nuitka-project: --file-version={MY_VERSION}

# The PySide6 plugin covers qt-plugins
# nuitka-project: --enable-plugin=pyside6
# nuitka-project: --include-qt-plugins=qml
```

--------------------------------

### Nuitka Project Options for GUI Applications

Source: https://nuitka.net/user-documentation/use-cases.html

Example of using Nuitka project options within a Python script to configure compilation modes and debugging settings based on the operating system.

```python
# Compilation mode, standalone everywhere, except on macOS and Linux
# there app bundle
# nuitka-project: --mode=app
#
# Debugging options, controlled via environment variable at compile time.
# nuitka-project-if: {OS} == "Windows" and os.getenv("DEBUG_COMPILATION", "no") == "yes"
#     nuitka-project: --windows-console-mode=hide
# nuitka-project-else:
#     nuitka-project: --windows-console-mode=disabled
```

--------------------------------

### Create hello.py

Source: https://nuitka.net/user-documentation/tutorial-setup-and-build.html

Create a Python file named hello.py with a simple function and main entry point.

```python
def talk(message):
    return "Talk " + message


def main():
    print(talk("Hello World"))


if __name__ == "__main__":
    main()
```

--------------------------------

### Enable Nuitka in setup.cfg

Source: https://nuitka.net/user-documentation/use-cases.html

Configuration to enable Nuitka compilation via the metadata section in setup.cfg.

```ini
[metadata]
build_with_nuitka = true
```

--------------------------------

### Display Nuitka help documentation

Source: https://nuitka.net/user-documentation/user-manual.html

Use the --help flag to view all available functionalities and command line options for Nuitka.

```bash
python -m nuitka --help

```

--------------------------------

### Enable Nuitka in setup.py

Source: https://nuitka.net/user-documentation/use-cases.html

Simple flag to enable Nuitka compilation within a setup.py file.

```python
# For setup.py
setup(
   ...,
   build_with_nuitka=True
)
```

--------------------------------

### Check for conda package

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Use is_conda_package to determine if a package was installed via conda.

```python
is_conda_package("shapely")
```

--------------------------------

### Create Project Directory

Source: https://nuitka.net/user-documentation/tutorial-setup-and-build.html

Create a new folder to house your Python project.

```bash
mkdir HelloWorld
```

--------------------------------

### Platform Specific DLL Inclusion

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Example of selecting architecture-dependent DLLs using platform-specific suffixes.

```yaml
- module-name: 'tls_client.cffi'

dlls:
   - from_filenames:
      relative_path: 'dependencies'
      prefixes:
         - 'tls-client'
      suffixes:
         - 'dll'
      when: 'win32'
   - from_filenames:
      relative_path: 'dependencies'
      prefixes:
         - 'tls-client'
      suffixes:
         - 'so'
      when: 'linux'
   - from_filenames:
      relative_path: 'dependencies'
      prefixes:
         - 'tls-client'
      suffixes:
         - 'dylib'
      when: 'macos'
```

--------------------------------

### Architecture Dependent DLL Inclusion

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Example of including DLLs located in subfolders based on the target architecture.

```yaml
- module-name: 'tkinterweb'

  dlls:
    - from_filenames:
        relative_path: 'tkhtml/Windows/32-bit'
        prefixes:
          - 'Tkhtml'
      when: 'win32 and arch_x86'
    - from_filenames:
        relative_path: 'tkhtml/Windows/64-bit'
        prefixes:
          - 'Tkhtml'
      when: 'win32 and arch_amd64'
```

--------------------------------

### EXE Configuration

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Configuring an executable file by setting the executable flag to yes.

```yaml
dlls:
  - from_filenames:
      prefixes:
        - 'subprocess'
      executable: 'yes'
  - from_filenames:
      prefixes:
        - ''  # first match decides
```

--------------------------------

### Configure Onefile Splash Screen

Source: https://nuitka.net/user-documentation/user-manual.html

Use these project directives and Python code to display a PNG splash screen during startup and remove it once the application is ready.

```python
# nuitka-project: --onefile
# nuitka-project: --onefile-windows-splash-screen-image={MAIN_DIRECTORY}/Splash-Screen.png

# Whatever this is, obviously
print("Delaying startup by 10s...")
import time, tempfile, os
time.sleep(10)

# Use this code to signal the splash screen removal.
if "NUITKA_ONEFILE_PARENT" in os.environ:
   splash_filename = os.path.join(
      tempfile.gettempdir(),
      "onefile_%d_splash_feedback.tmp" % int(os.environ["NUITKA_ONEFILE_PARENT"]),
   )

   if os.path.exists(splash_filename):
      os.unlink(splash_filename)

print("Done... splash should be gone.")
...

# Rest of your program goes here.
```

--------------------------------

### Configure Windows Icons

Source: https://nuitka.net/user-documentation/user-manual.html

Use these commands to set icons for Windows binaries using PNG, ICO files, or template executables.

```bash
python -m nuitka --onefile --windows-icon-from-ico=your-icon.png program.py
python -m nuitka --onefile --windows-icon-from-ico=your-icon.ico program.py
python -m nuitka --onefile --windows-icon-template-exe=your-icon.ico program.py
```

--------------------------------

### Include Data Files and Configuration with {MAIN_DIRECTORY}

Source: https://nuitka.net/user-documentation/user-manual.html

Demonstrates using the {MAIN_DIRECTORY} variable to specify paths for data files and user package configuration files relative to the main script.

```python
# nuitka-project: --include-data-files={MAIN_DIRECTORY}/my_icon.png=my_icon.png
# nuitka-project: --user-package-configuration-file={MAIN_DIRECTORY}/user.nuitka-package.config.yml
```

--------------------------------

### Anti-bloat plugin configuration flags

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

Example usage of anti-bloat plugin flags to ignore or error on specific package imports during compilation.

```bash
--noinclude-pytest-mode=nofollow --noinclude-setuptools-mode=nofollow
```

```bash
--noinclude-custom-mode=setuptools:error
```

--------------------------------

### Module implicit imports entry

Source: https://nuitka.net/user-documentation/nuitka-package-config.html

Example of declaring implicit imports for a module, where the module-name identifies the target and depends lists the required sub-modules.

```yaml
- module-name: 'pandas._libs'
  implicit-imports:
    - depends:
      - 'pandas._libs.tslibs.np_datetime'
      - 'pandas._libs.tslibs.nattype'
      - 'pandas._libs.tslibs.base'
```

--------------------------------

### Configure macOS App Bundle Icons

Source: https://nuitka.net/user-documentation/user-manual.html

Use these commands to create application bundles with icons on macOS.

```bash
python -m nuitka --macos-create-app-bundle --macos-app-icon=your-icon.png program.py
python -m nuitka --macos-create-app-bundle --macos-app-icon=your-icon.icns program.py
```

--------------------------------

### Fork Bomb Error Message

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

Example of an error message triggered when a Nuitka-compiled program attempts to call itself recursively, often caused by packages like multiprocessing.

```text
./hello.dist/hello.bin -l fooL -m fooM -n fooN -o fooO -p
Error, the program tried to call itself with '-m' argument. Disable with '--no-deployment-flag=self-execution'.
```

--------------------------------

### Accessing files in onefile mode

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

Demonstrates how to locate files relative to the executable or the unpacked temporary directory, and how to write code compatible with both onefile and standalone modes.

```python
# This will find a file *near* your onefile.exe
open(os.path.join(os.path.dirname(sys.argv[0]), "user-provided-file.txt"))
# This will find a file *inside* your onefile.exe
open(os.path.join(os.path.dirname(__file__), "user-provided-file.txt"))

# This will find a file *near* your onefile binary and work for standalone too
try:
   open(os.path.join(__compiled__.containing_dir, "user-provided-file.txt"))
except NameError:
   open(os.path.join(os.path.dirname(sys.argv[0]), "user-provided-file.txt"))
```

--------------------------------

### Create Onefile Binary with Temporary Unpacking

Source: https://nuitka.net/user-documentation/use-cases.html

This command creates a single binary that unpacks into a temporary folder upon execution.

```bash
# Create a binary that unpacks into a temporary folder
python -m nuitka --mode=onefile program.py
```

--------------------------------

### Common Memory-Related Compiler Error Messages

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

Examples of error messages from GCC, MSVC, and Zig that indicate the compiler has run out of memory or encountered internal errors during the build process.

```text
# gcc
fatal error: error writing to -: Invalid argument
Killed signal terminated program
{standard input}: Assembler messages:
{standard input}: Warning: end of file not at end of a line; newline inserted
# MSVC
fatal error C1002: compiler is out of heap space in pass 2
fatal error C1001: Internal compiler error
# zig
error: unable to build compiler_rt: OutOfMemory
error: sub-compilation of libubsan failed
    note: memory allocation failure
```

--------------------------------

### Build with Nuitka

Source: https://nuitka.net/user-documentation/tutorial-setup-and-build.html

Compile the Python script into an executable using Nuitka.

```bash
python -m nuitka hello.py
```

--------------------------------

### Configure Nuitka in pyproject.toml

Source: https://nuitka.net/user-documentation/use-cases.html

Using the Nuitka build backend in pyproject.toml to manage compilation and setuptools integration.

```toml
[build-system]
requires = ["setuptools>=42", "wheel", "nuitka", "toml"]
build-backend = "nuitka.distutils.Build"

# Data files are to be handled by setuptools and not Nuitka
[tool.setuptools.package-data]
some_package = ['data_file.txt']

[tool.nuitka]
# These are not recommended, but they make it obvious to have effect.

# boolean option, e.g. if you cared for C compilation commands, leading
# dashes are omitted
show-scons = true

# options with single values, e.g. enable a plugin of Nuitka
enable-plugin = "pyside2"

# options with several values, e.g. avoid including modules, accepts
# list argument.
nofollow-import-to = ["*.tests", "*.distutils"]
```

--------------------------------

### Benchmark Pystone Performance

Source: https://nuitka.net/user-documentation/performance.html

Shell commands to compare uncompiled Python execution against Nuitka-compiled binaries using LTO and PGO optimizations.

```bash
echo "Uncompiled Python2"
for i in {1..100}; do BENCH=1 python2 tests/benchmarks/pystone.py ; done | sort -rn | head -n 1
python2 -m nuitka --lto=yes --pgo tests/benchmarks/pystone.py
echo "Compiled Python2"
for i in {1..100}; do BENCH=1 ./pystone.bin ; done | sort -n | head -rn 1

echo "Uncompiled Python3"
for i in {1..100}; do BENCH=1 python3 tests/benchmarks/pystone3.py ; done | sort -rn | head -n 1
python3 -m nuitka --lto=yes --pgo tests/benchmarks/pystone3.py
echo "Compiled Python3"
for i in {1..100}; do BENCH=1 ./pystone3.bin ; done | sort -rn | head -n 1
```

--------------------------------

### Compile in Onefile Mode

Source: https://nuitka.net/user-documentation/use-cases.html

Use the --mode=onefile flag to create a single binary that extracts itself on the target system before execution.

```bash
python -m nuitka --mode=onefile program.py
```

--------------------------------

### Manual Plugin Loading with pkgutil

Source: https://nuitka.net/user-documentation/common-issue-solutions.html

Use pkgutil.iter_modules and importlib.import_module to scan and load plugins from a package directory, which is more robust for compiled code than manual file scanning and exec.

```python
# Using a package name to locate the plugins. Also, a good approach
# way to organize them into a directory.
scan_path = scan_package.__path__

for item in pkgutil.iter_modules(scan_path):
   importlib.import_module(scan_package.__name__ + "." + item.name)

   # You may want to do it recursively, but we don't do this here in
   # this example. If you'd like to, handle that in this kind of branch.
   if item.ispkg:
      ...
```

--------------------------------

### Compile in Standalone Mode

Source: https://nuitka.net/user-documentation/use-cases.html

Use the --mode=standalone flag to produce a folder containing the program and its dependencies.

```bash
python -m nuitka --mode=standalone program.py
```

--------------------------------

### Compile a whole package

Source: https://nuitka.net/user-documentation/use-cases.html

Use this command to compile an entire package. You must manually specify the package inclusion, and you can optionally exclude specific sub-modules like tests.

```bash
python -m nuitka --module some_package --include-package=some_package
```
Tokens:
Raw