# TK 4K

> Source: <https://dev.to/open-madscience/tk-4k-4f0o>
> Published: 2026-11-22 20:06:09+00:00

**Key takeaway:** tk4k 0.5.6 offers a Tk-shaped Python GUI API with no system Tcl/tkinter dependency, measuring 0.2% steady-state CPU for an idle window and 7.8% for an animated bar under Mesa software OpenGL on Linux.

## ALPHA: Linux only so far, and I am out of my depth here

**This is an alpha (`0.5.6`), built with Claude's help.** It is the one project of mine where I am completely out of my

depth: a GUI toolkit, a native renderer and a tkinter porter are well beyond what I can do alone. I am publishing it in

the hope that skilled people can pick up where I left off. Issues, pull requests and forks are very welcome.

**Tested on Linux only** (Tk 8.6, Python 3.12/3.13, headless). The wheel in `dist/` is Linux x86-64. **Not run on
Windows, Mac, a real GPU, a real 7th-gen Core i3 or a ROG Ally.** Other platforms: build from source (untested).
**Known gaps:** `place()`, fonts, ttk styling, Text embedded widgets and `overrideredirect` are only approximate; libraries
that need live Tcl widgets (turtle, idlelib, customtkinter...) are graded "unsafe" and point to `tk4k.classic`.
**Not measured:** how well the porter predicts problems on programs it has never seen, and the behaviour-difference
counts in docs/DIFFHUNT.md are not from held-out data.- Everything that was and was not tested is in
[docs/research/LOG.md](https://github.com/The-Dorkknight/tk4k/blob/main/docs/research/LOG.md) and the
[paper (PDF)](https://github.com/The-Dorkknight/tk4k/blob/main/docs/TK4K-paper.pdf).

[xkcd #353 "Python"](https://xkcd.com/353/) by Randall Munroe, [CC BY-NC 2.5](https://creativecommons.org/licenses/by-nc/2.5/).
  A copy is included in this repository (docs/img/xkcd353.png) under that licence; the Apache-2.0 licence of the code does not cover it. Thank you, Randall.

**A small, modern, Tk-shaped GUI toolkit for Python. About 0% CPU when nothing is happening.**

*Project started 2026-11-20 15:39. Version 0.2.0 (alpha), built 2026-11-21 23:59.*

``` python
import tk4k as ui

name = ui.Var("")
with ui.Window("Hello", size=(400, 200)) as win:
    ui.Label("Your name:")
    ui.Entry(var=name, hint="type here")
    ui.Button("Greet", on_click=lambda: win.toast(f"Hi {name.get() or 'there'}!"), primary=True)
win.run()
```

`TK4K-Demo-Linux.sh`` TK4K-Demo-Windows.bat``TK4K-Demo-Mac.command`
The launcher makes a private `.venv` inside the folder and installs the bundled wheel. Nothing system-wide changes.

You can also `pip install tk4k-*.whl` yourself. No system packages are needed, which is the point

(no `python3-tk`, no Tcl, nothing to fight on immutable distros such as Bazzite).

`Window`, `Row`, `Column`, `Grid`, `Label`,
`Button`, `Entry`, `Checkbox`, `Slider`, `Progress`), shared values (` Var` with `.trace`), timers (` win.after`),
and a 20-line app is 20 lines. It is `win.post(fn)` runs `fn` on the UI thread from any worker thread, and widget callbacks
never run in the middle of drawing, so changing the widget tree inside a callback is always safe.`tk4k.testing.Harness` fakes clicks and typing and takes screenshots
using SDL's dummy driver and its software renderer. The same renderer is the automatic fallback on
machines with no usable GPU.
All numbers are from one Linux sandbox (2 vCPU, Xvfb, Mesa software GL). **No real GPU, no Windows, no macOS and no 7th-generation Core i3 were available**, so nothing here is a promise about those machines.

`python scripts/benchmark.py` on yours.
| Case (Xvfb, 520x420 window) | Renderer | First frame | CPU, steady state | Frames in 4 s | Peak RSS | 
|---|---|---|---|---|---|
| Idle window | OpenGL ES (Mesa software) | 0.10 s | 0.20 % | 2 | 117 MB | 
| Idle window | SDL software | 0.10 s | 0.34 % | 2 | 119 MB | 
| One busy (animated) bar | OpenGL ES (Mesa software) | 0.09 s | 7.8 % | 80 (20 per second) | 117 MB | 
| One busy (animated) bar | SDL software | 0.10 s | 16.9 % | 80 | 119 MB | 
| Redraw at 60 fps all the time (for comparison) | OpenGL ES (Mesa software) | - | 20.1 % | 239 | - | 
| Redraw at 60 fps all the time (for comparison) | SDL software | - | 40.5 % | 241 | - | 

Install size: wheel 1.7 MB; compiled module 3.7 MB; font 24 KB. Memory is dominated by Mesa's software GL

libraries that SDL loads at start-up in this sandbox (about 55 MB of `libLLVM`); with SDL's dummy driver the same

app peaks at 23 MB. Finding out how to avoid that load is an open item.

The test suite (22 core tests, 8 for `tk4k.classic` that need Tk and a display, 15 for `tk4k.port` that need LibCST) passes on Python 3.12 and 3.13 using the same installed `abi3` wheel (v0.1.4: all 30 passed on a Python with no system tkinter plus the bundled `tk4k_tk` wheel; not repeated for 0.2.0).

| Works (tested here) | Written but **not tested** | Not there yet | 
|---|---|---|
| Linux, X11 (Xvfb) and dummy driver | Windows, macOS (including high-DPI scaling) | Wayland-specific testing | 
| Clicks, typing, Enter, checkbox, slider, layout, themes, timers, threads | Wheels for Windows/macOS/other Pythons (CI file never run) | Native OS file dialogs (in-app chooser instead) | 
| Software-renderer fallback | A real GPU renderer, real hardware, a real 7th-gen i3 | Per-tag fonts and colours in an *editable* Text (colours show when read-only) | 
| Idle behaviour (frames and CPU) | Input methods (IME) for CJK/accents | grid `rowspan` ; fonts other than the theme font | 
| Menus, tabs, combobox (read-only and editable), listbox, tree (tags, multi-select, drag via `move` ), canvas (items, images,`tag_bind` ), Text tags, PhotoImage (PNG/GIF/PPM, no Pillow needed) |  | Screen-reader support (today: none) | 
| `tk4k.classic` on Tk 9.0 and Tk 8.6 (Python 3.12, tested 2026-11-22) | `tk4k_tk` cp314 | Animated GIFs; JPEG and 16-bit PNG need Pillow | 
| Porting class-based apps; 40 hard test programs port and run |  |  | 

Known limits right now: if your code changes an `Entry`'s `Var` while that Entry has keyboard focus, the

on-screen text may not update until it loses focus (Dear ImGui keeps its own edit buffer while a field is active;

the Combobox already reloads it, the Entry does not yet). Every `after()` timer redraws 2-3 frames even if it changed nothing.

```
sh scripts/build_dev.sh          # needs cmake and a C++17 compiler; downloads SDL 3.4.8
PYTHONPATH=src python3 -m pytest tests -q
PYTHONPATH=src python3 examples/demo.py
```

On Linux you need the usual SDL build packages (X11/Wayland dev headers); `MINIMAL=1` skips the optional ones.

**0.5.6:** a differential hunt against real tkinter (tools/diffhunt, docs/DIFFHUNT.md) found and fixed dozens of behaviour differences (71 outside the by-design list became 27): Text's trailing newline and index errors, Treeview's "Item not found" errors and hex ids, Scale snapping, Entry/Listbox/Combobox index rules, `cget` read-back.

**0.5.5:** the porter now **predicts problems before a program runs** (missing methods, argument shapes, bindings that never fire, Tcl calls, common tkinter mistakes; see docs/ANTICIPATION.md), and TK 4K survives what it cannot do: a tkinter method it lacks is a logged no-op instead of a crash. On 194 unseen programs: failed to start 56 -> 42, unsafe grades 100 -> 25. Paper section 22.

**0.5.4:** 40 deliberately awkward components were ported, run, clicked and (five of them) compared with real Tk: first run 20 of 40 apps raised errors, now 0 start failures and 125 clicks with one known error. New: Text search/marks/undo, Entry selection, `onvalue/offvalue`, Scale `resolution`, `pack_info`/` grid_info`, `wait_variable`, `SimpleDialog`, base-`__init__` and `isinstance` porting. Paper section 21.

**0.5.3:** a whole real project (65 files, modules importing each other) was ported, run, compared with real Tk and every button clicked: 63 of 65 start (the other two are library modules). Fixes: `**options` forwarding, `*values`, default root, old-style `Var.trace`, name clashes with `size`/` open`/` close`/` run` in subclasses, expanding canvases. Details in the paper, section 20.

**0.5.2:** tested on a real standard-library app and a whole book of programs (see the paper, section 19): blocking file/ask dialogs, `Toplevel` subclasses, `Canvas.create_window`, `TclError`, colour names; two silent bugs fixed (centre anchor, `textvar=`). Apps built on turtle/idlelib/customtkinter-style libraries are flagged `unsafe` and belong on `python -m tk4k.classic`.

**0.5.1:** porting a folder can no longer be taken down by one file (worker processes, heartbeat, timeout, memory cap); `--jobs N`; files with nothing to translate are skipped faster.

**0.5.0:** images (`PhotoImage` on labels, buttons, canvas), Canvas `tag_bind` drag-and-drop, coloured Text tags, editable Combobox,

Treeview tag colours / multi-select / `move` / `identify_row`, `wm_attributes`, `event_generate`, `font.Font`. What the porter costs:

[docs/research/porting-tool/bench](https://github.com/The-Dorkknight/tk4k/tree/main/docs/research/porting-tool/bench).

**0.4.0:** menus, tabs, radio, spinbox, listbox, tree, canvas and pop-up dialogs are real widgets; class-based apps port. See `examples/hardest/`.

`tk4k.port`

```
TK4K-Port-Linux.sh my_app.py        # or double-click it / TK4K-Port-Windows.bat / TK4K-Port-Mac.command and drag a file in
python3 -m tk4k.port my_app.py      # needs LibCST:  pip install "tk4k[port]"   (QR codes: pip install segno)
python3 -m tk4k.port some_folder/ --check      # grade every tkinter file, write nothing
```

It writes `my_app_tk4k.py` next to the original (which is never touched) plus a JSON report and a log. **Nothing is silently dropped.** A widget TK 4K doesn't have yet (Spinbox, Listbox, Menu, Radiobutton...) becomes a greyed-out 

`ui.Placeholder` that`.get()` and swallows other calls; any other tkinter call becomes `ui.unsupported(...)`. So the translated app still` my_app_tk4k.port.log` (translation) and `my_app_tk4k.tk4k.log` (every run; `TK4K_LOG=0` turns it off).`TK4K1-...`) is printed, saved as a QR picture
(`.qr.png`, needs `segno`) and shown in the terminal. Read it with `python -m tk4k.port --decode TK4K1-...`.
If the optional `EC2-` string instead. (ErrCode is PolyForm Noncommercial, TK 4K is
Apache-2.0, so ErrCode is never bundled and never required.)
Grades: **safe** (no loss), **review** (approximations, e.g. fonts dropped, a message box became a toast), **unsafe**

(placeholders present: it runs, but features are missing), **failed** (the translator couldn't read the file; the reason is in

the report), **skipped** (class-based UI, planned `rename` mode). Exit status 0 / 1 / 2 for fine / unsafe / failed.

Status: prototype. It handles UIs built in straight-line code with the widgets TK 4K has; details and measurements in

`docs/research/porting-tool/`.

`tk4k.classic`
Run an existing tkinter program, unchanged, on real Tk with TK 4K's look:

```
python3 -m tk4k.classic my_old_app.py          # Linux Mint etc.: needs tkinter (sudo apt install python3-tk)
TK4K_THEME=light python3 -m tk4k.classic -m idlelib
```

It uses Tk's own option database and a generated ttk theme, so the app's behaviour does not change; colours the app sets itself

still win, and canvases are left alone. Cost measured here: +25-40 ms start-up, +1-2 MB. It is honestly "a prettier Tk": the bigger

upgrade path is planned in **`docs/COMPAT_PLAN.md`** (v3): a small, tested kernel that answers tkinter's commands, with Tk's odd parts as on-demand modules and this skin as the fallback.

**No tkinter at all (Bazzite and other immutable systems)?** `dist/` has `tk4k_tk` wheels (3.6 MB) with real Tcl/Tk 9 for

CPython 3.13 and 3.14 on 64-bit Linux:

```
python3 -m venv ~/.tk4k && ~/.tk4k/bin/pip install dist/tk4k_tk-*-cp313-*.whl dist/tk4k-*.whl
~/.tk4k/bin/python -m tk4k.classic my_old_app.py
```

(cp313 was tested on a Python without tkinter; cp314 is built but untested; Tk 8.6, Mint's version, could not be tested here.)

Scan any tkinter code for what it uses (reads, runs nothing): `python scripts/tk_scan.py app/ --json s.json && python scripts/tk_scan_report.py s.json`

`docs/COMPAT_PLAN.md`: plan v3 for legacy tkinter apps (kernel + on-demand modules + fallback); v1 and v2 are in `docs/research/compat/`.` docs/research/hard-parts/`: Tk's source measured by subsystem, what apps use of Text and Canvas, cheap building blocks found.`docs/research/porting-tool/` and `docs/PORT_TOOL_DESIGN.md`: the tkinter → TK 4K translator (` docs/research/classic-skin/`: the skin's screenshots, measurements and bugs found; `docs/research/LOG.md`: the dated log.` docs/DESIGN.md`: how it works, every decision and why, the roadmap and the open items.`docs/RESEARCH_NOTES.md`: what already exists, what I checked, and what is only from memory (part 2: tkinter compatibility).`docs/TK4K-paper.pdf`: the illustrated, easier-to-read version of the above.` docs/benchmarks.md`: the raw benchmark output.
**Source code:** [The-Dorkknight/tk4k on GitHub](https://github.com/The-Dorkknight/tk4k)
