nuitka-build - SKILL.md Agent Skill

name: nuitka-build description: Build Python/PyQt6 apps into standalone executables using Nuitka

Nuitka Build Skill

Build ClawdBot UI into standalone executables for Windows and macOS using Nuitka.

What is Nuitka?

Nuitka compiles Python code to native C executables. Benefits:

Faster execution - Compiled to native code
No Python required - Standalone distribution
PyQt6 support - Built-in plugin
Cross-platform - Windows, macOS, Linux

Installation

pip install nuitka

Local Build Commands

Windows (Single .exe)

python -m nuitka --mode=onefile --enable-plugin=pyqt6 --windows-console-mode=disable --output-dir=dist main.py

Windows (Folder distribution)

python -m nuitka --mode=standalone --enable-plugin=pyqt6 --windows-console-mode=disable --output-dir=dist main.py

macOS (.app bundle)

python -m nuitka --mode=app --enable-plugin=pyqt6 --macos-app-icon=assets/clawdbot.png --output-dir=dist main.py

GitHub Actions with Nuitka-Action

Use Nuitka-Action for CI/CD builds.

Workflow Structure

- name: Build with Nuitka
  uses: Nuitka/Nuitka-Action@main
  with:
    nuitka-version: main
    script-name: main.py
    mode: onefile           # or standalone, app
    enable-plugins: pyqt6
    windows-console-mode: disable
    output-file: MyApp

Key Options

Option	Values	Description
`mode`	`onefile`, `standalone`, `app`	Output type
`enable-plugins`	`pyqt6`, `pyside6`	UI framework
`windows-console-mode`	`disable`, `attach`	Hide console
`windows-icon-from-ico`	Path	Windows .ico icon
`macos-app-icon`	Path	macOS .png/.icns icon
`output-file`	Name	Output filename

Current Project Workflow

Located at: .github/workflows/build.yml

Triggers:

GitHub Release published
Manual (workflow_dispatch)

Builds:

Platform	Mode	Output
Windows	onefile	`ClawdBot-Control-Panel-Windows.exe`
macOS	app	`ClawdBot-Control-Panel-macOS.app.zip`

Steps:

Checkout code
Setup Python 3.13
Install UV + dependencies
Build with Nuitka-Action
Upload artifacts + attach to release

Requirements

Windows

Visual Studio Build Tools OR MinGW64 (auto-downloaded by Nuitka)

macOS

Xcode Command Line Tools
xcode-select --install

Both

Python 3.13+
C compiler (auto-handled in GitHub Actions)

Common Issues

Missing DLLs (Windows)

Use --mode=standalone first to debug, then switch to --mode=onefile.

PyQt6 not found

Ensure --enable-plugin=pyqt6 is set.

Large file size

Normal for PyQt6 apps (~50-100MB). Nuitka includes Qt libraries.

Console window appears

Add --windows-console-mode=disable.

Tips

Test locally first before pushing to GitHub Actions
Use standalone mode for debugging
Check build output for missing modules
Add --show-progress for verbose local builds