PuiKit

PuiKit is a capability-based Python UI framework that supports both TUI (terminal) and GUI (desktop, web) backends. Build apps and widgets once, run them on multiple backends without splitting implementations.

Apps and widgets specify what to draw (intent)
How to draw (implementation) is decided by the backend
Backends declare their capabilities; the Panel layer resolves fallbacks
Widget code never branches on TUI/GUI

See the documentation for design notes and per-system guides (layout, rendering, color, animation, fonts, widgets, and more).

Screenshots

The bundled demo catalog, running unchanged on the macOS GUI backend and in a terminal (curses backend).

macOS GUI backend	Curses (terminal) backend

Apps built with PuiKit

XeFM — a dual-pane file manager that runs as a native desktop app on Windows and macOS, and in the terminal on all platforms, from a single codebase. PuiKit's first and most demanding user: archive / SFTP / S3 browsing, rich built-in viewers, and themes with GPU background shaders and CRT post effects.
Keyhac 2 — Python-scriptable keyboard customization for Windows and macOS, successor to Keyhac for Windows and Keyhac for macOS. Its UI is built on PuiKit.

Building something with PuiKit? Open an issue or PR to get it listed here.

Status

Stable release (1.0). Implemented:

Core framework: Panel, Backend interface, capability profiles, event model
Layout system: HSplit / VSplit / Item with weights and min_px / min hints — snapped to whole base units on TUI, resolved at pixel granularity on GUI
Animation: panel.animate(widget, hints={"transition": "fade", "duration_ms": 200}) — transitions fade (opacity), slide (position), scale (visual zoom), size (layout reflow), and highlight (color) rendered on the macOS backend; immediate switch on TUI
Widgets: Label, ListView, ScrollBar, Container
Widget tree: containers nest widgets with hierarchical clipping; animations on a parent cascade to all descendants, while children stay individually animatable
Backends:
- CursesBackend — TUI, all platforms
- MacOSBackend — macOS native GUI (PyObjC, installed automatically on macOS)
- WindowsBackend — Windows native GUI (raw ctypes; Direct2D/DirectWrite)
- WebBackend — runs in a web browser, launched with webbrowser over a local WebSocket (--backend web; see docs/web_backend.md)
- MemoryBackend — headless, for tests
Planned next: C++ CoreText render extension

Quick start

pip install puikit

That's all you need — the base install ships a working TUI on every platform, and a native window on macOS (PyObjC installs automatically; on Windows the curses backport installs automatically). The minimal app below then runs as-is, with no repository checkout required.

Want to see it move right away? The hello-world example is a single self-contained file — download and run it without cloning the repo:

curl -O https://raw.githubusercontent.com/crftwr/puikit/main/examples/hello_world/main.py

python3 main.py                  # TUI — in a terminal, any platform
python3 main.py --backend gui    # native window — macOS
python3 main.py --backend web    # opens a browser tab — any platform

Minimal app

from puikit import EventType, Panel
from puikit.backends import create_backend
from puikit.widgets import Label

backend = create_backend("tui")
with backend:
    panel = Panel(backend)
    panel.add(Label("Hello, PuiKit!"), x=2, y=1, w=30, h=1)
    panel.render()

    def on_event(event):
        if event.type is EventType.KEY and event.key == "q":
            backend.quit()
            return
        panel.dispatch_event(event)
        panel.render()

    backend.run_event_loop(on_event)

Run it in a terminal for the TUI backend, or pass --backend gui (macOS) / --backend web (any platform) if you wire up argument handling like the bundled examples.

Development (from source)

Clone the repository, then install editable with the dev extras:

python3.14 -m venv .venv
.venv/bin/pip install -e ".[dev]"

# Run the examples (in a terminal)
.venv/bin/python examples/hello_world/main.py
.venv/bin/python examples/demo_catalog/main.py

# On macOS, the same examples in a native window
.venv/bin/python examples/hello_world/main.py --backend gui
.venv/bin/python examples/demo_catalog/main.py --backend gui

# Or in a web browser (opens a tab; works on any platform)
.venv/bin/python examples/demo_catalog/main.py --backend web

# Run the tests
.venv/bin/python -m pytest

Contact & Support

GitHub Issues: Report bugs or request features
PyPI: pypi.org/project/puikit — released versions (pip install puikit)
Author's X (Twitter): @crftwr

License

See LICENSE.

Metadata

Release files for puikit 1.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for puikit 1.13.0
File	Size	Uploaded	Provenance
puikit-1.13.0.tar.gz	29.4 MB	Oct 22, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for puikit 1.13.0
File	Interpreter	ABI	Platform	Reset
puikit-1.13.0-py3-none-any.whl 29.2 MB Oct 22, 2026 Without provenance	Python 3	none	any	Details

Total release size: 58.6 MB

Release files / puikit-1.13.0.tar.gz

Download URL	puikit-1.13.0.tar.gz
Size	29.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`a7517ad3ac9d7498e555019a5a857dd2a4c04d6b5040a8e354238595047b3a1d`
BLAKE2b-256 checksum How to use checksums	`96b151532bf3ccb0dbe81d7f87d349740ba22a467d3f36a62ec278bdddcbbf41`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / puikit-1.13.0-py3-none-any.whl

Download URL	puikit-1.13.0-py3-none-any.whl
Size	29.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`e10e1f58a1b23e93db7fe42053ccc4841e3588e854aa9e1b0d346294c6faf395`
BLAKE2b-256 checksum How to use checksums	`f98198159ab4fcb0acda560be542fd4487771f5d3fe174e7e1fe6ff0c8058ad2`
Upload date	Oct 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Security for puikit 1.13.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.