guile 0.4.0

A lightweight Python framework for building native desktop apps.

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 native window with a clean interface, nothing more.

Inspired by the early design of the Julia language — which set out to take the best of Python, R, and MATLAB rather than compromise between them — guile tries to do the same for Python GUIs. In that spirit: guile has the syntax of Streamlit, the single-process simplicity of Tkinter, and the visual polish of a modern web app, without requiring you to write HTML, CSS, or JavaScript.

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. This is different from Streamlit, which re-executes the whole script and redraws the page on every interaction.

• No nesting hell. Layout is written top to bottom using with blocks, not by nesting constructors inside constructors. with gui.card(): followed by indented widget calls reads the same way the finished UI looks — no inside-out tree building, no closing parentheses to track.

• No server. The app runs as a single Python process and opens a native OS window. There is no local HTTP server, no port to bind, no browser tab to manage. This also means packaging with PyInstaller produces a self-contained executable with no runtime dependencies for the end user.

---

Install

pip install pywebview

Copy the guile/ folder into your project. No further setup.

---

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

File	What it shows
01_counter.py	State, buttons, badges
02_todo.py	Lists, dynamic rendering, checkboxes
03_settings.py	Sliders, selects, form layout
04_geo_data.py	Matplotlib figure + Leaflet map
05_data_tools.py	Table, date picker, file picker
06_soil_water.py	Sliders driving a live chart

---

Dependencies

Package	Purpose
pywebview	Native window
matplotlib	Only if you use gui.figure()
numpy	Only if your app uses it

Everything else is Python standard library.

---

Files

File	Role
state.py	Reactive value class
ui.py	Render engine + all widgets
_app.py	Window lifecycle, pywebview bridge
_template.py	Embedded HTML/CSS/JS
__init__.py	Public API (gui.*)

See ARCHITECTURE.md for a deeper explanation of how the files connect.

---

Versions

v0.1.0 First release including docs, reference, and 27 widgets. AP on 22 May 2026

v0.2.0 Added max_height argument to gui.scroll() widget Replaced onchange for onblur in gui.multiselect() widget

v0.3.0 Added notify and modal widgets Created new examples and improved existing examples

v0.4.0 Added tabs Fixed the datetime-local input to display in 24-hour format by setting lang="en-GB"

MIT License