nicegui-pyodide

Run stock NiceGUI entirely in the browser via Pyodide / PyScript — no server, no websocket, no backend — as an external extension.

No fork. No patches to NiceGUI's source. This package makes an unmodified pip install nicegui importable and runnable under Pyodide from the outside, by weaving a set of sys.modules shims in before import nicegui.

This is the extension re-implementation of the upstream Pyodide effort (zauberzeug/nicegui#5776), which required editing ~25 core files. Here that lives entirely in a separate package instead.

Why an extension instead of a PR?

The PR approach had to touch NiceGUI core in ~25 places — wrapping every from fastapi import … / from socketio import … in try/except ImportError and adding if IS_PYODIDE: branches. That is invasive and hard to merge.

Pyodide has no server: there is no uvicorn, no socket.io, and NiceGUI's server-only imports (fastapi, starlette, uvicorn, aiofiles, anyio, ifaddr) simply don't exist. So a plain import nicegui explodes before any of your code runs.

This extension solves it from outside core:

1. A sys.meta_path finder fabricates a permissive stub module for every import under those absent packages — rich enough (subclassable, callable, decorator-friendly, operator-safe) that stock NiceGUI's unguarded usages don't crash: class App(FastAPI), @app.post(url), class APIRouter(fastapi.APIRouter), class CacheControlledStaticFiles(StaticFiles), Jinja2Templates(path). (nicegui_pyodide/_shims.py)
2. A lazy nicegui.nicegui seed supplies the app singleton without running stock nicegui/nicegui.py — which would build the FastAPI app + socket.io server + HTTP routes. Stock nicegui/__init__.py does from .nicegui import app; the import machinery finds the seed first.
3. An in-process JS bridge replaces socket.io: Python emit() calls hop straight to JavaScript over the Pyodide FFI. (bridge.py, outbox.py, runtime.py)
4. A pyodide-patched nicegui.js (shipped as an asset, pinned to a NiceGUI version) that talks to the bridge instead of a websocket. All new paths are gated on window.niceguiBridge, so the file is backward-compatible with server mode.

On a normal (server) Python this package is inert — import nicegui behaves exactly as usual — so shared code can import it unconditionally.

Usage

pip install nicegui-pyodide            # pulls in a compatible nicegui
nicegui-pyodide-build ./dist --serve   # build + serve → http://localhost:8080

--serve builds and serves in one step; without it, nicegui-pyodide-build ./dist just assembles the dir and you serve it however you like (python -m http.server -d ./dist 8080).

Edit dist/app.py to change the UI, then reload the page. Re-running nicegui-pyodide-build ./dist refreshes the generated files but keeps your app.py (pass --force to reset it to the starter template). The app-building pattern:

import nicegui_pyodide                 # MUST come before `import nicegui`
from nicegui import Client, ui
from nicegui_pyodide import page

with Client(page('/')) as client:
    ui.label('Hello from the browser!')
    ui.button('Click me', on_click=lambda: ui.notify('Clicked!'))
# the generated entrypoint mounts `client` via PyodideRuntime

For coding agents / LLMs

This package uses a different idiom from server-mode NiceGUI. If you know NiceGUI, these are the things you'll get wrong on the first try:

• Build the UI in a with Client(page('/')) as client: block — do not call ui.run() or ui.run_with(). There is no server to start; both raise a RuntimeError telling you this. @ui.page server routes don't exist either.
• import nicegui_pyodide MUST come before import nicegui (it installs the import shims). Keep the # noqa: F401 on it so linters don't "helpfully" delete the line, and don't let an import-sorter move it below import nicegui. Getting this wrong raises a clear RuntimeError rather than failing silently.
• The workflow is build-a-static-bundle, not python app.py: nicegui-pyodide-build ./dist --serve, then edit dist/app.py and reload.
• No backend features: app.add_static_files, HTTP endpoints, native/multiprocessing modes are unavailable. Root-relative asset paths (/foo.png) won't resolve — use absolute URLs or data:/blob: URIs. See the support matrix below.

A copy of these rules also lives in AGENTS.md.

Element support matrix

Most NiceGUI elements are pure client-side Vue and work unchanged. A handful assume a live server (a socket.io connection or a component static route) and therefore need special handling in the browser. Status against the pinned NiceGUI release:

The overridden/shimmed elements (scene, leaflet, xterm) are the socket.io/handshake and static-route cases that would otherwise fail with an opaque TypeError (window.socket is undefined) or a silent missing-stylesheet; all three are covered by the browser smoke test. Genuinely server-bound features (last row) are documented as unsupported rather than patched.

Version pinning

nicegui_pyodide/static/nicegui.js is a pyodide-patched copy of a specific NiceGUI release's nicegui.js. The nicegui>=3.14,<3.15 pin in pyproject.toml keeps them in lockstep. To support a newer NiceGUI, regenerate the patched JS against that release and widen the pin.

Status / limitations

• Verified in-browser (Chromium via Playwright): render, button click → handler → DOM update, ui.notify, input round-trip through the bridge, ui.upload round-trip, on_connect handlers, and app.storage.tab.
• File upload works client-side: files are read in the browser (FileReader → base64) and delivered over the bridge to runtime._handle_upload (no server route).
• @ui.page server routes are not available (there is no server); use the Client(page(...)) pattern shown above.
• Anything needing a real backend (HTTP endpoints, app.add_static_files, multiprocessing, native mode) is a no-op or unavailable in the browser.

License & attribution

This project is MIT-licensed (see LICENSE), Copyright (c) 2026 evnchn.

It bundles modified copies of a few files from NiceGUI (MIT, © Zauberzeug GmbH): nicegui_pyodide/static/nicegui.js and the component overrides under nicegui_pyodide/static/component_overrides/ (markdown.js, leaflet/leaflet.js, xterm/xterm.js). See NOTICE for details. Other vendor assets (Quasar, Vue, Tailwind, …) are copied from your own installed NiceGUI at build time and are not redistributed in this repository.

The Pyodide mechanism re-implemented here originated in the author's own upstream PR, zauberzeug/nicegui#5776 (closed).