Install & Compatibility
Where this runs
tested against v3.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.724s · 105.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 10.7s · import 2.536s · 111MB
121MB installed
● package 121MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ui
✓ from nicegui import ui
The primary object for building UI elements and running the application.
app
✓ from nicegui import ui, app
The 'app' object is used for advanced features like custom FastAPI routes, sub-pages, or running NiceGUI within an existing FastAPI application.
This minimal example creates a web page with a 'Hello NiceGUI!' label and a button that displays a notification when clicked. Running this script will open the application in your browser.
from nicegui import ui
ui.label('Hello NiceGUI!')
ui.button('Click me!', on_click=lambda: ui.notify('Hello from NiceGUI!'))
ui.run()
nicegui --version
Debug
Known issues
breakingSince v3.8.0, `run_method()` and `run_*_method()` no longer accept arbitrary JavaScript expressions as method names. Only actual method names are supported for security reasons.fixRewrite `run_method()` calls to use explicit method names instead of inline JavaScript functions.
affects: >=3.8.0
breakingIn v3.0.0, the `ui.html` element now requires a `sanitize` argument to prevent Cross-Site Scripting (XSS) attacks. `ui.chat_message` also has this argument, especially if `text_html=True`.fixWhen using `ui.html`, explicitly set `sanitize=True` (or provide a custom sanitizer function) or `sanitize=False` if you are certain the content is safe.
affects: >=3.0.0
gotchaSeveral security vulnerabilities related to Cross-Site Scripting (XSS) via unsanitized user input (e.g., in `ui.markdown()`, user-defined links, and sub-pages) have been addressed across multiple versions (v3.5.0, v3.7.0). Always sanitize or validate any user-provided content before rendering it.fixKeep NiceGUI updated to the latest version. Always use the `sanitize` argument where available for user-generated content, or implement your own robust sanitization for all user inputs displayed in the UI.
affects: All versions, especially prior to v3.7.0
gotchaVulnerabilities related to file handling (e.g., filename sanitization bypass in `ui.upload` v3.10.0, path traversal via `FileUpload.name` v3.7.0, and arbitrary file access via `app.add_media_files` v3.4.0) have been reported. Be cautious when exposing uploaded or local files.fixEnsure NiceGUI is up-to-date. Carefully review security implications when using file upload features (`ui.upload`) or exposing local directories (`app.add_media_files`, `add_static_files`). Avoid putting security-critical files in exposed directories.
affects: All versions, especially prior to v3.10.0
breakingWith v3.0.0, the `ui.element.tailwind` API was removed. Upgrading to Tailwind 4 also introduced some breaking changes in layout and styling.fixMigrate from the deprecated `ui.element.tailwind` API. Review your UI layouts after upgrading, especially for styling with Tailwind CSS, as line spacing and borders might differ. Use `element.classes()` for Tailwind CSS utility classes.
affects: >=3.0.0
breakingIn NiceGUI 3.0, you must directly modify `table.rows`, `table.columns`, or `aggrid.options` instead of using methods like `table.add_rows()` to update table data.fixAdjust code to directly manipulate the data properties of table elements. `table.update()` or `aggrid.update()` are not necessary after direct property modification.
affects: >=3.0.0
gotchaMemory exhaustion via media streaming routes (v3.9.0) was a security vulnerability. Ensure your application handles media streaming efficiently and is updated to prevent such resource attacks.fixUpgrade to NiceGUI v3.9.0 or later to address the memory exhaustion vulnerability.
affects: <3.9.0
Errors
Common errors & fixes
RuntimeError: This event loop is already running
This error occurs when attempting to call `ui.run()` in an environment where an asyncio event loop is already active, such as a Jupyter notebook, an IDE's interactive console, or when trying to run multiple instances of `ui.run()`.
fixIf running in an interactive environment (like a Jupyter notebook), install and use `nest_asyncio` by adding `import nest_asyncio; nest_asyncio.apply()` at the beginning of your script. Otherwise, ensure `ui.run()` is called only once, typically in the main execution block of your application, for example, within `if __name__ == '__main__':`.
AttributeError: module 'nicegui.ui' has no attribute 'context'
This error indicates that the `ui.context` object, which provides access to client-specific information and methods, is not available in the NiceGUI version you are using. This typically happens with older NiceGUI versions where `ui.context` had not yet been introduced or its usage changed significantly.
fixUpdate NiceGUI to the latest version (`pip install --upgrade nicegui`) to gain access to `ui.context` and its features. If upgrading is not an option, you may need to refactor your code to avoid `ui.context` or use an older API compatible with your NiceGUI version.
TypeError: __init__() got an unexpected keyword argument 'icon'
This `TypeError` often arises when using an argument (like `icon` for `ui.button`) that has been renamed, removed, or has changed its expected type or position in a different version of NiceGUI than the one your code expects.
fixConsult the official NiceGUI documentation for your installed version to verify the correct arguments for the specific UI component you are using. If you are following an example, ensure your NiceGUI version matches the example's requirements, or update NiceGUI (`pip install --upgrade nicegui`) to match the latest documentation.
ModuleNotFoundError: No module named 'httpx'
This error signifies that your Python environment is missing a required third-party library, like `httpx`, which your NiceGUI application or an example code snippet depends on.
fixInstall the missing package using pip. For `httpx`, the command would be `pip install httpx`. Always check the `requirements.txt` file if available for the project or example you are trying to run to ensure all dependencies are installed.
AttributeError: module 'webview' has no attribute 'settings'
This error occurs when attempting to run a NiceGUI application in native desktop mode (e.g., `ui.run(native=True)`) with an incompatible or outdated version of the `pywebview` library.
fixUpgrade your `pywebview` library to a version compatible with your NiceGUI installation. A common fix is to run `pip install --upgrade pywebview`. Refer to the NiceGUI documentation or GitHub issues for specific `pywebview` version requirements if the upgrade alone does not resolve the issue.
Upgrade
Version history
3.16.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer, but less than Python 4.