NiceGUI Configuration And Deployment¶

Use this reference when a NiceGUI task concerns ui.run(...) settings, runtime URLs, native windows, environment variables, server hosting, executable packaging, or NiceGUI On Air. For startup ownership, app factories, ui.run_with(...), lifespan, reload, and workers, load FastAPI and Uvicorn startup.

The public surfaces below follow NiceGUI's current configuration and deployment documentation. Inspect the target project's pinned NiceGUI version before relying on a recently added option or native-mode behavior.

Configure The Owning Runtime¶

Choose the process owner before setting runtime options:

Do not split ownership by calling ui.run() and a separate server launcher for the same app. The exact composition patterns and worker constraints are in FastAPI and Uvicorn startup.

Select ui.run Options Deliberately¶

ui.run(...) accepts several groups of settings:

Additional keyword arguments are forwarded to uvicorn.run. Most ui.run option changes require stopping and fully restarting the process; do not assume development auto-reload applies them.

Read Runtime URLs After Binding¶

app.urls contains the URLs on which the running app is available. The server has not bound its sockets during app.on_startup, so the collection is not available there. Read it in a page function or subscribe to app.urls.on_change when another application component needs the final addresses.

from nicegui import app, ui


@ui.page('/')
def home() -> None:
    for url in app.urls:
        ui.link(url, target=url)


ui.run()

Do not derive a public URL solely from the listening host and port when a reverse proxy, container port mapping, or tunnel owns the external address.

Configure Environment-Controlled Facilities¶

NiceGUI recognizes these framework environment variables:

Treat these as process-start configuration. For application-owned host, port, credentials, feature flags, and service settings, use one validated settings model rather than scattering direct environment reads. When multiple processes or executables share local storage, do not let them independently rewrite the same files; give each instance a distinct NICEGUI_STORAGE_PATH or configure Redis where state must be shared.

Deploy A Browser-Hosted App¶

Run the production entry point under a service manager or container restart policy. NiceGUI's multi-architecture Docker image runs an application mounted at /app; its default internal port is 8080, so publish that port explicitly. The image supports non-root execution through PUID and PGID and passes process signals through to the app.

docker run --detach --restart always \
    --publish 80:8080 \
    --env PUID="$(id -u)" \
    --env PGID="$(id -g)" \
    --volume "$PWD:/app" \
    zauberzeug/nicegui:latest

For HTTPS, either pass Uvicorn's ssl_certfile and ssl_keyfile options to ui.run(...) or terminate TLS at a reverse proxy such as NGINX or Traefik. A reverse-proxy deployment must preserve NiceGUI's HTTP and Socket.IO traffic, forwarding scheme and host information, route prefixes, timeouts, and upload limits consistently. Verify the rendered page, static assets, websocket connection, reconnect behavior, and upload path through the public URL rather than only against the container port.

Use one worker by default. NiceGUI clients, element trees, tasks, and ordinary Python state are process-local; a multi-worker deployment needs compatible session affinity and externalized shared state. See FastAPI and Uvicorn startup before adding workers or combining them with reload.

Build A Native Desktop App¶

ui.run(native=True) launches a pywebview window. window_size, fullscreen, and frameless cover common presentation settings. Configure lower-level pywebview behavior before startup through:

• app.native.window_args for webview.create_window arguments
• app.native.start_args for webview.start arguments
• app.native.settings for pywebview settings
• app.native.main_window for asynchronous access to the running window

Values in window_args and start_args take precedence over overlapping ui.run arguments. The browser engine must support ES modules and import maps; use Chrome 89 or newer, a current WebKitGTK or Qt backend on Linux, and the EdgeChromium prerequisites used by pywebview on Windows. A local Windows favicon used as the native icon must be an .ico file.

Native mode chooses an available port automatically when port is omitted. Browser mode defaults to 8080; use native.find_open_port() explicitly when multiple browser-mode executable instances must coexist.

Native Events And Process Placement¶

Register sync or async handlers with app.native.on(...). Supported lifecycle and window events are shown, loaded, minimized, maximized, restored, resized, moved, closed, and drop. Resized and moved events expose dimensions or coordinates in event.args; drop events expose filesystem paths under event.args['files'].

The native UI runs in a separate process. Define app.native.window_args, start_args, settings, and event registrations outside the if __name__ == '__main__': guard so the child process sees them.

from nicegui import app, ui

app.native.window_args['resizable'] = False
app.native.on('drop', lambda event: print(event.args['files']))

if __name__ == '__main__':
    ui.run(native=True, reload=False)

Native storage follows the same scopes as browser mode. Multiple executable instances started from one working directory can collide on the default .nicegui files; isolate NICEGUI_STORAGE_PATH per instance or use Redis for intentionally shared state.

Package An Executable¶

Both nicegui-pack/PyInstaller and Nuitka require an import-safe application:

1. Disable auto-reload with ui.run(reload=False, ...).
2. Supply a root page callable to ui.run or register at least one @ui.page.
3. Decide whether the executable opens a browser or uses native=True.
4. Use an available port when simultaneous instances are valid.
5. Exercise the built artifact on every target operating system; a successful build on the development host does not establish runtime compatibility.

With nicegui-pack, --onefile is convenient but starts more slowly because PyInstaller extracts it on each run. A directory build starts faster and can be archived for distribution. Use --windowed only with native=True; a browser-mode application without a console has no normal Ctrl-C exit surface.

Nuitka must include both NiceGUI modules and package data because NiceGUI uses lazy imports and ships frontend assets:

python -m nuitka \
    --onefile \
    --include-package=nicegui \
    --include-package-data=nicegui \
    main.py

Add equivalent package and package-data flags for optional libraries that ship templates or frontend assets. Prefer --standalone when startup speed matters more than producing one file.

Multiprocessing In Packaged Native Apps¶

Packaged native apps must call multiprocessing.freeze_support() as the first statement inside the main guard to prevent recursive process creation. Keep native settings outside the guard so the spawned native process applies them.

from multiprocessing import freeze_support

from nicegui import app, ui

app.native.window_args['transparent'] = True


def root() -> None:
    ui.label('Packaged app')


if __name__ == '__main__':
    freeze_support()
    ui.run(root, native=True, reload=False)

Use On Air Only For Deliberate Remote Access¶

ui.run(on_air=True) creates a temporary public URL, currently valid for one hour. A private device token can select a stable organization/device URL. Treat that token as a secret, and do not log or commit it.

NiceGUI On Air is a tech preview, not a substitute for selecting an authentication, authorization, availability, and data-governance model. Before exposing an application, review what data and actions become reachable, add application authentication where needed, and verify the service's current operational and privacy terms. Use ordinary hosted deployment when the application requires controlled networking, durable availability, or organization-owned TLS and access policy.

Deployment Verification¶

Validate the built deployment through its real entry point and public boundary:

• process starts with reload disabled and shuts down cleanly under the service manager or container runtime
• health route, root page, static assets, Socket.IO connection, and reconnect flow work through the proxy or published port
• app.urls is consumed only after server binding and is not mistaken for canonical proxy configuration
• storage survives and isolates users, tabs, workers, and executable instances as designed
• TLS, forwarded headers, cookie flags, upload limits, cache policy, and logs match the public deployment
• a native build opens, handles window events, closes cleanly, and can run alongside another instance when supported
• packaged artifacts include NiceGUI and optional-library data files and are tested on each target platform
• normal background tasks cancel on shutdown, while only explicitly bounded finalization work uses @background_tasks.await_on_shutdown; see interaction mechanics

Sources¶