guile

A lightweight Python framework for building desktop apps.

Philosophy

Guile started as a personal tool for building lab and research apps — the kind of quick internal dashboards, data explorers, and parameter tools that are too specific to justify a full web stack, but too interactive for a script. The goal was always to stay out of the way: write Python top to bottom, get a window with a clean interface, nothing more.

It is not trying to compete with NiceGUI, PyQt, or Dash. It is the right tool for a simple lab, company, or personal project — and deliberately nothing more.

A few specific choices that shape how guile feels:

• No full-page refresh. When state changes, only the parts of the UI that actually changed are updated. Text stays in inputs, sliders don't jump, focus is never lost.
• No nesting hell. Layout is written top to bottom using with blocks. with gui.card(): followed by indented widget calls reads the same way the finished UI looks.
• No server. The app runs as a single Python process and opens a window. There is no local HTTP server, no port to bind, no browser tab to manage.

Install

pip install guile

Requires pywebview. On Windows, WebView2 ships with Windows 10/11 — nothing extra to install.

Quick start

import guile as gui

count = gui.state(0)

@gui.app("Counter", width=400, height=300)
def ui():
    with gui.col(align="center", justify="center", style="height:100vh"):
        with gui.card(gap=14):
            gui.title("Counter")
            with gui.row(gap=16, align="center", justify="center"):
                gui.button("−", variant="secondary",
                           on_click=lambda: count.update(lambda x: x - 1))
                gui.text(count, size="2xl", bold=True,
                         style="min-width:64px;text-align:center")
                gui.button("+",
                           on_click=lambda: count.update(lambda x: x + 1))

How it works

• gui.state(value) — a reactive value; setting it re-renders the UI automatically
• with gui.card(): / with gui.col(): / with gui.row(): — layout containers; everything indented goes inside
• gui.button(), gui.slider(), gui.input(), gui.table() — widgets that take on_click= or return their current value
• gui.figure(fig) — embed a matplotlib figure inline
• gui.leaflet(center, markers=...) — embed an interactive map

Examples

Dependencies

Everything else is Python standard library.

Files

Changelog

v0.5.0 — Added center=True to app window. Improved code structure in how-to page.

v0.4.0 — Added tabs. Fixed datetime-local input to display in 24-hour format.

v0.3.0 — Added notify and modal widgets.

v0.2.0 — Added max_height to gui.scroll(). Fixed multiselect change event.

v0.1.0 — First release. 27 widgets.

MIT License