Guide · Open source
How to use NiceGUI: install, run your first UI and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
NiceGUI is an open-source Python framework for building web user interfaces. You describe buttons, dialogs, labels and other elements in Python code, and the framework shows them in a web browser. This guide walks through installing it, running a first page and the features that matter for small apps, dashboards and tools.
NiceGUIzauberzeug/nicegui · ★ 16.3k · MIT Install options & downloads Quick start
- 1Install the package. Run python3 -m pip install nicegui in a terminal. Python 3 is required.
- 2Create main.py. Add from nicegui import ui, then your elements, then ui.run().
- 3Start the script. Run python3 main.py from the folder that contains the file.
- 4Open the page. Visit http://localhost:8080/ in your browser.
- 5Edit and watch it reload. Change the code and save. NiceGUI reloads the page automatically.
- 6Explore the docs. Work through the live demos at nicegui.io/documentation.
Install NiceGUI with pip
NiceGUI is available as a PyPI package, so you install it with pip. The only prerequisite listed is Python 3.
python3 -m pip install niceguiWrite your first NiceGUI page
Create a file named main.py. Import ui from nicegui, add elements such as a label and a button, and call ui.run() at the end. The button here shows a notification when it is pressed.
from nicegui import ui
ui.label('Hello NiceGUI!')
ui.button('BUTTON', on_click=lambda: ui.notify('button was pressed'))
ui.run()Run the app and open it in your browser
Start the script with python3 main.py. The page is then available at http://localhost:8080/ in your browser. NiceGUI reloads the page automatically when you modify the code, so you can edit and see changes without restarting by hand.
python3 main.pyKnow what elements and features you can use
NiceGUI includes standard elements such as label, button, checkbox, switch, slider, input and file upload. You group them with rows, columns, cards and dialogs. For more specialised needs, the README lists plots and charts, 3D scenes, Markdown, tables, video and audio, and a built-in timer that can refresh data at intervals.
- Standard elements: label, button, checkbox, switch, slider, input, file upload
- Layout: rows, columns, cards, dialogs
- Data: built-in timer, data binding and refreshable functions
- Persistence: per-user and general persistence
- Modes: web server or native mode such as a desktop window
- Also runs in Jupyter Notebooks and Python's interactive mode
Find examples and documentation
The documentation at nicegui.io/documentation includes live demos. The full nicegui.io site is built with NiceGUI itself, and you can start it locally with Docker or by running main.py from the repository. The repository also has in-depth examples and a wiki with community projects, tutorials and FAQs.
docker run -p 8080:8080 zauberzeug/niceguiUse NiceGUI with AI assistants
If you build with an AI assistant, the README suggests pointing it at nicegui/llms.md, a concise reference that ships with the package.
What people use it for
- A quick web interface for a Python script or internal tool
- A dashboard showing data that refreshes at set intervals
- Controls for a robotics project or smart home setup
- Tuning machine learning or motor controller settings through a browser UI
- Running a UI in a desktop window instead of a browser tab
Frequently asked questions
Is NiceGUI free to use?
NiceGUI is released under the MIT licence, as stated in the project's README and repository. Check the LICENSE file in the repository for the full terms.
What do I need to install NiceGUI?
The listed prerequisite is Python 3. You install the package from PyPI with python3 -m pip install nicegui. It is also available as a Docker image and on conda-forge.
How do I run a NiceGUI app?
Save your code in a file such as main.py and run python3 main.py. Then open http://localhost:8080/ in your browser.
Do I need to write JavaScript to use NiceGUI?
No. The README says all UI logic is written in Python, and the framework handles the web details. This is also why it is not a fit for teams that want to write their UI in JavaScript or TypeScript.
How does NiceGUI compare to Streamlit?
The README says the Zauberzeug team likes Streamlit but finds it does too much magic with state handling. NiceGUI was created as an alternative for simple Python GUIs. Other comparable projects named are JustPy, Gradio and Dash.
Is NiceGUI ready for large public production websites?
The README centres on Python-driven UIs rather than custom JavaScript pages, and it does not address a verified production security or scaling track record. For large public sites that need heavy custom front-end work, look at other options and evaluate carefully.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
NiceGUI suits Python developers who want a browser UI for a script, dashboard or hardware or smart home project, and it can also run in a desktop window. If you need heavy custom front-end work, a JavaScript or TypeScript UI, or a proven track record for large public production sites, consider a different tool.
Install options & downloads