Python Micro GUI

A quick gui for scripts that dont care about asthetics.

Installation

pip install microgui

or

uv add microgui

System Prerequisites

Because microgui compiles a native C extension (bridge.c) during installation, your system needs a C compiler and development headers:

Linux (Ubuntu/Debian):

sudo apt-get install build-essential libx11-dev

Windows: Install Visual Studio Build Tools and check the "Desktop development with C++" workload.

macOS: Currently Unsupported

Quick Start

Even though you install microgui, you import the library as mui in your code for simplicity. Here is how to spin up a basic window loop:

import mui.ui as ui

win = ui.Window(title="Micro GUI Window", width=500, height=500)

# will evaluate to True as long as the window is open
while win:
    # actually manages the window and needs to run in loop
    with win:
        ui.label("Hello Micro GUI")

microgui vs Tkinter (Multi-Window Comparison)

When building multi-window applications, traditional frameworks like Python's built-in tkinter require complex object-oriented inheritance, tracking window lifecycle instances manually, and writing messy event callbacks.

Because microgui uses an immediate-mode pipeline, creating and managing multiple windows is entirely sequential, flat, and stateless.

The Tkinter Approach (Retained-Mode Architecture)

To manage two windows in Tkinter cleanly, you have to track parent-child tracking states and pass window instances through classes:

import tkinter as tk

class ControlWindow:
    def __init__(self, root):
        self.root = root
        self.root.title("Control Panel")
        
        # Really complicated stuff
        self.display_win = tk.Toplevel(root)
        self.display_win.title("Display Panel")
        
        self.label = tk.Label(self.display_win, text="Status: Idle")
        self.label.pack()
        
        self.btn = tk.Button(root, text="Trigger", command=self.update_status)
        self.btn.pack()

    def update_status(self):
        # Callbacks to update state
        self.label.config(text="Status: Active!")

root = tk.Tk()
app = ControlWindow(root)
root.mainloop()

The MicroGUI Approach (Immediate-Mode Architecture)

In microgui, windows are just IDs. You switch drawing contexts on the fly inside a single, readable loop. No classes, no callbacks, and no state synchronization bugs:

import mui.ui as ui

app = ui.Application()
win_control = app.create_window("Control Panel", 400, 300)
win_display = app.create_window("Display Panel", 400, 300)

status_text = "Status: Idle"

while app:
    # draw into the control window
    with win_control:
        if ui.button("Trigger"):
            status_text = "Status: Active!" # global variable available to all windows
            
    # draw into the display window
    with win_display:
        ui.label(status_text)

Why choose one over the other?

	Micro GUI	Traditional Frameworks(PyQT/PySide, Tkinter or Kivy)
Use Case	Quick GUI for debugging or developer focused tools	Retained GUI with complex state and customization
Structure	Simple loops, conditionals and context managers.	OOP, classes and state.
Styling	It looks the way it looks. Focus on functionality	Complex styling with configuration and complex layout systems
Functionality	Conditionals manage everything, no complexity involved.	Events, Callbacks and sometimes Threads