nicegui

NiceGUI

NiceGUI is an easy-to-use, Python-based UI framework, which shows up in your web browser. You can create buttons, dialogs, markdown, 3D scenes, plots and much more.

It is great for micro web apps, dashboards, robotics projects, smart home solutions and similar use cases. You can also use it in development, for example when tweaking/configuring a machine learning algorithm or tuning motor controllers.

NiceGUI is available as PyPI package, Docker image and on GitHub.

Features

• browser-based graphical user interface
• implicit reload on code change
• standard GUI elements like label, button, checkbox, switch, slider, input, file upload, ...
• simple grouping with rows, columns, cards and dialogs
• general-purpose HTML and markdown elements
• powerful high-level elements to
  • plot graphs and charts,
  • render 3D scenes,
  • get steering events via virtual joysticks
  • annotate and overlay images
  • interact with tables
  • navigate foldable tree structures
• built-in timer to refresh data in intervals (even every 10 ms)
• straight-forward data binding to write even less code
• notifications, dialogs and menus to provide state of the art user interaction
• shared and individual web pages
• ability to add custom routes and data responses
• capture keyboard input for global shortcuts etc
• customize look by defining primary, secondary and accent colors
• live-cycle events and session data

Installation

python3 -m pip install nicegui

Usage

Write your nice GUI in a file main.py:

from nicegui import ui

ui.label('Hello NiceGUI!')
ui.button('BUTTON', on_click=lambda: ui.notify('button was pressed'))

ui.run()

Launch it with:

python3 main.py

The GUI is now available through http://localhost:8080/ in your browser. Note: NiceGUI will automatically reload the page when you modify the code.

Documentation and Examples

The API reference is hosted at https://nicegui.io/reference and provides a ton of live examples. The whole content of https://nicegui.io is implemented with NiceGUI itself.

You may also have a look at the following examples for in-depth demonstrations of what you can do with NiceGUI:

• Slideshow: implements a keyboard-controlled image slideshow
• Authentication: shows how to use sessions to build a login screen
• Modularization: provides an example of how to modularize your application into multiple files and create a specialized @ui.page decorator
• Map: uses the JavaScript library leaflet to display a map at specific locations
• AI User Interface: utilizes the great but non-async API from https://replicate.com to perform voice-to-text transcription and generate images from prompts with Stable Diffusion
• 3D Scene: creates a 3D scene and loads an STL mesh illuminated with a spotlight
• Custom Vue Component shows how to write and integrate a custom vue component
• Image Mask Overlay: shows how to overlay an image with a mask
• Infinite Scroll: shows an infinitely scrolling image gallery

Why?

We like Streamlit but find it does too much magic when it comes to state handling. In search for an alternative nice library to write simple graphical user interfaces in Python we discovered JustPy. While we liked the approach, it is too "low-level HTML" for our daily usage.

Therefore we created NiceGUI on top of JustPy, which itself is based on the ASGI framework Starlette (like FastAPI) and the ASGI webserver Uvicorn.

Docker

You can use our multi-arch Docker image:

docker run --rm -p 8888:8080 -v $(pwd):/app/ -it zauberzeug/nicegui:latest

This will start the server at http://localhost:8888 with the code from your current directory. The file containing your ui.run(port=8080, ...) command must be named main.py. Code modification triggers an automatic reload.

Deployment

To deploy your NiceGUI app, you will need to execute your main.py (or whichever file contains your ui.run(...)) on your server infrastructure. You can either install the NiceGUI python package via pip on the server or use our pre-built Docker image which contains all necessary dependencies (see above). For example you can use this docker run command to start the script main.py in the current directory on port 80:

docker run -p 80:8080 -v $(pwd)/:/app/ -d --restart always zauberzeug/nicegui:latest

The example assumes main.py uses the port 8080 in the ui.run command (which is the default). The --restart always makes sure the container is restarted if the app crashes or the server reboots. Of course this can also be written in a docker compose file:

nicegui:
  image: zauberzeug/nicegui:latest
  restart: always
  ports:
    - 80:8080
  volumes:
    - ./:/app/

While it is possible to provide SSL certificates directly through NiceGUI (using JustPy config), we also like reverse proxies like Traefik or NGINX. See our docker-compose.yml as an example.