Tk has been around for exactly 2000 years and has more patches than a quilt factory.

TK 4K is the new blank-et, ready for another 2000 years of patches.

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 and the paper (PDF).

xkcd 353: Python. A person floats in the sky: 'I just typed import antigravity ... I also sampled everything in the medicine cabinet for comparison. But I think this is the Python.'
xkcd #353 "Python" by Randall Munroe, CC 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.

TK 4K demo, dark theme, with a background job running

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() 

Try it (one step)

  1. Download the zip from the Releases page and unzip it.
  2. Double-click TK4K-Demo-Linux.sh (choose Run), TK4K-Demo-Windows.bat or TK4K-Demo-Mac.command (right-click, Open, the first time).

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).

What it is

  • Tk-shaped: a retained widget tree you build in plain Python (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 not call-compatible with tkinter (see the design doc for why).
  • Modern: dark and light themes (or follow the OS), one font, crisp scaling on high-DPI screens, rounded widgets, a theme is one small dataclass.
  • Light: the loop sleeps inside the OS until something happens and draws only after input, a state change or a timer.
  • Self-contained: a 1.7 MB wheel, no runtime dependencies. SDL3 and Dear ImGui are compiled in.
  • Safe to thread: 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.
  • Tested without a screen: 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.

What was measured (and what was not)

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.
Run 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).

Honest status

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.

Build from source

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.

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

Port a tkinter app to TK 4K: 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
answers .get() and swallows other calls; any other tkinter call becomes ui.unsupported(...). So the translated app still
runs, and says what is missing:

translated app with placeholders

  • Alerts: a framed warning when you translate, a toast and an exit summary when you run the result.
  • Logs: my_app_tk4k.port.log (translation) and my_app_tk4k.tk4k.log (every run; TK4K_LOG=0 turns it off).
  • QR error report: when something is unsafe or fails, a short report string (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 ErrCode plug-in is installed, the same events are recorded as ErrCode codes 901-906 and the report becomes an ErrCode EC2- string instead. (ErrCode is PolyForm Noncommercial, TK 4K is Apache-2.0, so ErrCode is never bundled and never required.)

QR error report

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/.

Old tkinter apps, new look: 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 

plain Tk vs tk4k.classic dark and light vs sv-ttk

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

Documents in this repository

  • 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 (tk4k.port): research, design, results.
  • docs/research/classic-skin/: the skin's screenshots, measurements and bugs found; docs/research/LOG.md: the dated log.
  • docs/research/compat/: the v1 research (static scans, runtime Tcl logs, build order, corpus) and the superseded v1 plan.
  • 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