NiceGUI Tutorial: Build a Python GUI App in 5 Minutes

NiceGUI is a Python framework for building web GUIs. Vue and Quasar render the frontend on top of FastAPI, Tailwind CSS handles styling, and everything you write stays in Python. This NiceGUI tutorial gets a working Python GUI running in about five minutes, then covers what changed in 3.x and how to run the app in production.

As of October 2026 NiceGUI is at version 3.18.0 (released 2026-10-07), with 16.3k GitHub stars, roughly 890k PyPI downloads per month, and an MIT license maintained by Zauberzeug. It requires Python 3.10 or newer.

Over time I checked a few Python frameworks like Streamlit and Taipy before deciding to stick with NiceGUI. Streamlit is faster for a throwaway dashboard; NiceGUI wins when I want control over layout, styling, and speed. If you are still choosing, see the Streamlit vs. NiceGUI comparison, Streamlit vs Taipy, or the full list of Python web UI frameworks.

Every snippet below runs on NiceGUI 3.18.0. That is the point of a NiceGUI tutorial: install it, copy the code, verify it serves on port 8080.

NiceGUI Features

These are the parts that matter when you build a Python GUI with NiceGUI, and the ones I keep using in real apps:

That is not the full list. Check the NiceGUI documentation for the component reference.

Getting Started With NiceGUI

In the next sections you install NiceGUI, run a first page, and then walk through the components and customizations used in most apps. Bitdoze Tools is built with NiceGUI if you want to see a deployed example.

Install and Run NiceGUI

What you need before the pip command:

pip install nicegui

uv add nicegui

Create a file called main.py:

from nicegui import ui

ui.label('Hello NiceGUI!')

ui.run()

The anatomy is always the same:

• from nicegui import ui imports the module, like most other UI frameworks.
• The middle is your UI. ui.label('Hello NiceGUI!') puts text on the page; everything else below is variations on this line.
• ui.run() starts the server.

Run it:

python3 main.py

Verify: NiceGUI prints the URL and serves on http://localhost:8080. In a terminal you can confirm with:

curl -s -o /dev/null -w "%{http_code}" http://localhost:8080

You want 200. A blank response or Connection refused means the process died or the port differs; read the terminal output.

One 3.x nuance worth knowing now: code in the global scope like the example above is a “NiceGUI script”. It works, but the UI is re-created on every page visit and cannot be shared across clients. When you outgrow that (shared headers, multiple URLs), you move to @ui.page functions or ui.run(root=...). That is what the add multiple pages to NiceGUI guide covers.

Add Markdown

Formatted text goes through ui.markdown:

ui.markdown('# This is H1 Header')
ui.markdown('## This is H2 Header')
ui.markdown('### This is H3 Header')

Markdown headers map straight to HTML headings: one # is an H1, two are an H2, three are an H3.

Add Rows

# row element
with ui.row():
  ui.label(' First row item')
  ui.label(' Second row item')
  ui.label(' Third row item')

This creates a row layout: the labels sit side by side, horizontally. Put whatever elements you need inside the with ui.row(): block.

Add Columns

# Column element
with ui.column():
  ui.label(' First column item')
  ui.label(' Second column item')
  ui.label(' Third column item')

Same idea, stacked vertically. ui.column() is the default container in most of my pages; ui.row() when I need things next to each other.

Styling Components with Tailwind Classes

with ui.column():
  ui.label(' First column item').classes('font-bold')
  ui.label(' Second column item').classes('text-2xl')
  ui.label(' Third column item').classes('text-red-600 text-2xl')

.classes() takes any Tailwind utility classes. NiceGUI 3.x ships Tailwind CSS 4, and the common utilities (font-bold, text-2xl, text-red-600, shadow-lg, rounded-lg) behave the same as before. In 3.x these classes are also observable: changing them updates the browser immediately, without an .update() call.

Inputs and Buttons (Your First Interaction)

with ui.row():
    ui.input(label='Type Something').props('square outlined dense').classes('shadow-lg')
    ui.button('Click Me')

This adds an input with a label and a button in a row. .props() sets Quasar props (square outlined dense is a Quasar prop trio), while .classes() adds Tailwind classes. Mixing the two is the normal styling workflow.

Static elements are fine, but the point of a Python GUI is calling Python. Here is the smallest useful NiceGUI button on_click example:

from nicegui import ui

with ui.card():
    name = ui.input(label='Your name')
    ui.button('Greet', on_click=lambda: ui.notify(f'Hello, {name.value}!'))

ui.run()

Here is what happens: on_click registers a Python callback for the button. name.value reads whatever is in the input at click time. ui.notify(...) pops a small toast message on the page. Run it, type your name, click Greet. That is a working interactive app in seven lines.

Add Images

ui.image('https://picsum.photos/id/24/600/400').classes('h-auto max-w-lg rounded-lg flex justify-center')

ui.image takes a URL (or a local file path in your project) and the usual Tailwind classes apply: automatic height, capped width, rounded corners, centered on the page. Prefer a local asset or a stable URL in real apps; hashed build artifacts move when you rebuild the site.

Add Header with Drawer Toggle

with ui.header(elevated=True).style('background-color: #3874c8').classes('items-center justify-between'):
        ui.label('HEADER')
        ui.button(on_click=lambda: right_drawer.toggle(), icon='menu').props('flat color=white')

This creates a colored header bar with a title label and a hamburger button that toggles a right-side drawer. Note that the button references right_drawer before it is defined in the file; that works because the lambda runs later, at click time.

Add Right Sidebar/Drawer

with ui.right_drawer(fixed=False).style('background-color: #ebf1fa').props('bordered') as right_drawer:
        ui.label('RIGHT DRAWER')

The as right_drawer part is what the header button calls .toggle() on. Keep the header block before this one in the file so the variable reads naturally.

Add Footer

with ui.footer().style('background-color: #3874c8'):
        ui.label('FOOTER')

A footer pinned to the bottom of the page. Split it into ui.row() sections or columns if you need link groups.

Add Custom Code to the Header

ui.add_head_html('''
    <script></script>
    ''')

ui.add_head_html injects raw HTML into the page <head>. That is how you add JavaScript, custom CSS, or an analytics snippet.

The Complete Example File

Put everything together and the file looks like this:

from nicegui import ui

# demonstrate h1 and others
ui.markdown('# This is H1 Header')
ui.markdown('## This is H2 Header')
ui.markdown('### This is H3 Header')

ui.separator()

# row element
with ui.row():
  ui.label(' First row item')
  ui.label(' Second row item')
  ui.label(' Third row item')


ui.separator()
# Column element
with ui.column():
  ui.label(' First column item')
  ui.label(' Second column item')
  ui.label(' Third column item')

# style the text
ui.separator()

with ui.column():
  ui.label(' First column item').classes('font-bold')
  ui.label(' Second column item').classes('text-2xl')
  ui.label(' Third column item').classes('text-red-600 text-2xl')

# other elements
ui.separator()
with ui.row():
    ui.input(label='Type Something').props('square outlined dense').classes('shadow-lg')
    ui.button('Click Me')


# image add
ui.separator()
ui.image('https://picsum.photos/id/24/600/400').classes('h-auto max-w-lg rounded-lg flex justify-center')


# header with right drawer
with ui.header(elevated=True).style('background-color: #3874c8').classes('items-center justify-between'):
        ui.label('HEADER')
        ui.button(on_click=lambda: right_drawer.toggle(), icon='menu').props('flat color=white')
with ui.right_drawer(fixed=False).style('background-color: #ebf1fa').props('bordered') as right_drawer:
        ui.label('RIGHT DRAWER')

# footer
with ui.footer().style('background-color: #3874c8'):
        ui.label('FOOTER')


ui.run()  # dev: http://localhost:8080, auto-reload, opens your browser
# server/prod: ui.run(host='0.0.0.0', port=8080, reload=False, show=False, storage_secret='change-me')

Verify: python3 main.py, then open http://localhost:8080. You should see the markdown headers, the row and column items, the red bold text, the input and button, the image, the blue header with a menu button, and the footer. Click the menu button: the right drawer slides in.

This scratches the surface of what NiceGUI can do, but it is enough to understand the building blocks. Next, wire the buttons and inputs to your Python functions (see the on_click example above), then take a look at the production setup further down.

NiceGUI 3.x: What Changed Since 2.x

If you last touched NiceGUI when this article was first published, you are on 1.x-era code. The version history looks like this:

• 1.4.x in March 2024 (when this article went live)
• 2.0.0 on 2024-08-31, when the project adopted semantic versioning
• 3.0.0 on 2025-10-03, with the breaking changes listed below
• 3.18.0 on 2026-10-07, the current release

The beginner-relevant parts of the v3.0.0 release:

• The shared auto-index page is gone. You now pick one of three models: a plain script (global scope, like this tutorial), ui.run(root=my_function) for a single-page app, or @ui.page functions everywhere. Do not mix global-scope UI with @ui.page in the same file.
• .props(), .classes(), and .style() are observable. Delete the follow-up .update() calls.
• ui.table, ui.aggrid, ui.echart, ui.json_editor, ui.tree: mutate table.rows / aggrid.options directly instead of rebuilding the original Python lists.
• Tailwind CSS 4 replaced Tailwind 3.4. The element.tailwind Python API was removed. Standard utility classes still work.
• Python 3.8 support was dropped. Today the package requires Python 3.10+.
• ui.html and ui.chat_message(text_html=True) now take an explicit sanitize argument.
• Upload event handlers get a single e.file object (.name, .content_type, .read(), .save()) instead of separate content/name/type args.
• ui.open became ui.navigate.to.

Worth exploring once the basics work: ui.sub_pages for SPA navigation, make_sortable() for drag and drop (3.11), ui.popup (3.15), ui.parallax (3.9), app.colors theming (3.6), and ui.on_exception (3.6).

Run NiceGUI in Production (Docker + Reverse Proxy)

Once the app works locally, you need somewhere to run it. For most internal tools and small public apps a 4-5 EUR/month VPS from Hetzner Cloud is enough CPU and RAM. This tutorial’s example app is one small Python process, so even the cheapest tier has headroom.

NiceGUI runs as a single uvicorn worker with full async I/O. Do not scale it by adding workers. For CPU-bound work use run.cpu_bound(...) to push jobs into a process pool instead.

Production ui.run() flags

import os
from nicegui import ui

ui.label('Hello from production')

ui.run(
    host='0.0.0.0',
    port=8080,
    reload=False,
    show=False,
    storage_secret=os.environ['STORAGE_SECRET'],
)

services:
  nicegui:
    image: zauberzeug/nicegui:latest
    container_name: nicegui_app
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./app:/app
      - nicegui_storage:/app/.nicegui
    environment:
      - PUID=1000
      - PGID=1000
      - STORAGE_SECRET=change-me-to-a-long-random-string

volumes:
  nicegui_storage:

server {
    listen 443 ssl;
    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Verify after docker compose up -d:

docker compose logs -f nicegui   # uvicorn startup line, no tracebacks
curl -I http://localhost:8080    # HTTP/1.1 200 OK

Through the proxy, open browser devtools and confirm the WebSocket request returns 101 Switching Protocols. If it returns 404 or hangs, your proxy is not forwarding the upgrade headers.

If you want the general patterns for containerizing Python apps, see how to run any Python app in Docker with Docker Compose. The same compose layout works for FastHTML, Streamlit, or a plain FastAPI service.

Rollback is one command: docker compose down. Add -v only when you intend to delete the .nicegui storage volume as well.

One demo-only option: ui.run(on_air=True) gives you a temporary public tunnel URL. It is labeled a tech preview; fine for showing something to a colleague, not for production.

For a parallel deployment walkthrough, including TLS via tunnels, see how to deploy Streamlit on a VPS behind Cloudflare Tunnels. If you would rather keep everything at home, you can self-host NiceGUI on a home server mini PC at zero hosting cost plus electricity.

First-Run Errors and Fixes

The five failures you are most likely to hit, with the actual error first.

Why Some Will Probably Not Like NiceGUI

NiceGUI gives you a fast, fully customizable Python UI. The price of that control is CSS. At some point you will write Tailwind classes or tweak Quasar props to get the look you want, and if you have never touched CSS that feels like a wall in the beginning. Streamlit is the other path: throw code at it and the framework makes decisions for you. For a quick internal dashboard that trade is often right.

NiceGUI 3.x softened the curve slightly (Tailwind 4 is simpler than 3, and ui.sub_pages removes a lot of routing glue), but the trade-off is unchanged: control versus magic. If you want a performant Python GUI you can shape, NiceGUI is the better fit.

Conclusions

This NiceGUI tutorial took you from pip install nicegui through layout, Tailwind styling, a first interactive button, and a production deployment with Docker and a reverse proxy. The code was verified on NiceGUI 3.18.0, current as of October 2026.

Next steps: the NiceGUI documentation for the full component list, and the multi-page guide once you need routing. If you use AI coding agents, one practical tip: NiceGUI ships a compact API reference at nicegui/llms.md inside the pip package (also at nicegui.io/llms.txt). Paste that into your agent instead of scraping the docs site.