Skip to content

Document packaging with Nuitka - #6010

Merged
falkoschindler merged 1 commit into
mainfrom
docs/nuitka-packaging
Apr 30, 2026
Merged

Document packaging with Nuitka#6010
falkoschindler merged 1 commit into
mainfrom
docs/nuitka-packaging

Conversation

@falkoschindler

Copy link
Copy Markdown
Contributor

Motivation

NiceGUI's nicegui/ui.py resolves submodules lazily via a module-level __getattr__ (PEP 562). Nuitka's static analyzer can't trace importlib.import_module(module_path, ...) when module_path comes from a dict lookup, so submodules like nicegui.ui_run, nicegui.functions.style, and most nicegui.elements.* get pruned from Nuitka builds. PyInstaller side-steps this because nicegui-pack already passes --add-data <nicegui dir>.

Users have been hitting this for a while:

Both are unblocked by passing --include-package=nicegui --include-package-data=nicegui. This PR documents that.

Implementation

Adds a "Packaging with Nuitka" section to the deployment docs, between the existing PyInstaller block and the generic "Packaging with Native Mode" notes. Same structure as the PyInstaller demo: intro paragraph with flag rationale, 2-column python_window/bash_window pair with a working example, and a tips list covering --standalone vs --onefile, optional packages with their own data files, native-mode flags per platform, and build-time / cache notes.

The recommended invocation was verified locally — clean venv on Python 3.11.7 with Nuitka 4.0.8 + this branch's nicegui produced a 191 MB onefile binary that successfully resolves all lazy imports (ui.label, ui.add_css) used in #6009's repro.

Progress

  • Title starts with a verb
  • Implementation complete
  • Not a security issue
  • Pytests not necessary
  • Documentation added
  • No breaking changes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@falkoschindler falkoschindler added documentation Type/scope: Documentation, examples and website review Status: PR is open and needs review labels Apr 29, 2026
@falkoschindler falkoschindler added this to the 3.12 milestone Apr 29, 2026
@falkoschindler
falkoschindler requested a review from evnchn April 29, 2026 08:42
@evnchn

evnchn commented Apr 29, 2026

Copy link
Copy Markdown
Collaborator

@falkoschindler looks correct. Do you want to YOLO this or want Windows testing on my side?

@falkoschindler

Copy link
Copy Markdown
Contributor Author

@evnchn Let's YOLO and improve on demand.

@evnchn evnchn left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

YOLO it is, then

@falkoschindler
falkoschindler added this pull request to the merge queue Apr 30, 2026
Merged via the queue into main with commit 42b05bd Apr 30, 2026
7 checks passed
@falkoschindler
falkoschindler deleted the docs/nuitka-packaging branch April 30, 2026 00:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Type/scope: Documentation, examples and website review Status: PR is open and needs review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

When using nuitka for packaging, lazy imports will throw a ModuleNotFoundError

2 participants