App as module fails when reloading is enabled (with wrong error message)

[NichtJens]

First Check

• I added a very descriptive title here.
• This is not a security issue (those should be reported via the security advisory instead).
• This is not a Q&A. I am sure something is wrong with NiceGUI or its documentation.
• I used the GitHub search to find a similar issue and came up empty.

Example Code

Description

• Create folder called xxx.
• Add empty file __init__.py into xxx.
• Add file __main__.py into xxx with below contents.
• From level above xxx run python -m xxx.

__main__.py:

from nicegui import ui
ui.label("xxx")
ui.run(reload=True)

This crashes with:

You must call ui.run() to start the server.
If ui.run() is behind a main guard
   if __name__ == "__main__":
remove the guard or replace it with
   if __name__ in {"__main__", "__mp_main__"}:
to allow for multiprocessing.

ERROR:    Application startup failed. Exiting.

After changing to ui.run(reload=False), it runs as expected. From this, I would conclude that the automatic reloading has problems reloading apps written as modules. Is this expected?

The error message is wrong since the code definitely has ui.run() and does not hide it behind a wrong guard.

NiceGUI Version

3.12.0

Python Version

3.13.13

Browser

Firefox

Operating System

Linux

Additional Context

No response

[evnchn]

Thanks for the report, @NichtJens — and you're right that the message is misleading. The example clearly calls ui.run() and there's no main guard to remove.

Unfortunately the underlying behavior can't really be salvaged: python -m <pkg> invokes <pkg>/__main__.py, and CPython's multiprocessing.spawn deliberately refuses to re-execute __main__.py files in spawn children (Lib/multiprocessing/spawn.py:_fixup_main_from_name). The reload subprocess therefore never runs your top-level code, so ui.run() is never called there. Routing around that would mean bypassing a deliberate CPython policy and running user code as a side effect of importing NiceGUI — not a trade we want to make.

What we can fix is the message itself. #6068 detects this specific case and replaces it with an accurate hint naming the actual constraint and the two working alternatives (reload=False, or invoking python <pkg>/__main__.py directly). See the PR for the full reasoning and the salvager alternative that was prototyped and rejected.

[evnchn]

TL-DR for above: yes enhance error message, but sorry no can't let you do what you are doing due to CPython policy. Read #6068 for more details.