What's New in Tkinter

Core Development
1

What changed in tkinter — past month

python/cpython main, window ≈ 2026-06-09 → 2026-07-10 · ~74 commits touching the tkinter module, tests, and docs.

The month’s most important work was documentation and tests — and not only because they were the largest by far (+7,200 lines of docs, +4,400 lines of tests, against ~1,800 lines of library code). For the first time tkinter’s full public API is actually documented, and large parts of the package that had no automated tests at all now have them. That matters on its own, and it is also what made the rest of the month safe: the API could be expanded and long-standing bugs fixed against a real regression net and an accurate reference. The code changes below sit on that foundation.

1. Documentation overhaul — the full public API, documented at last

tkinter has long been under-documented, with users pushed to the Tcl/Tk man pages to fill the gaps. This month the reference was greatly expanded to cover the full public API of the package and all its submodules (gh-86726) — the largest single change of the month (+7,200 lines across 35 commits), and a sustained multi-part effort rather than one patch:

  • Full public-API coverage, with descriptions oriented toward Python rather than Tcl/Tk, corrected return types, and proper versionadded / versionchanged markers (gh-86726, PR #151579).
  • Restructured the reference (gh-86726, PR #152109), documented method-name conflicts (PR #151917) and the simpledialog query options / Dialog.result (PR #151851), and fixed long-standing errors — the info_patchlevel() return type (PR #151655) and the wm_attributes deprecated directive (PR #151652).
  • Docstrings: every tkinter and tkinter.ttk widget class now lists all supported options, including those added in Tk 9.0 / 9.1 (gh-78335); Menubutton and Message previously had no option list at all.
  • Numerous topic clarifications: the cursor option (gh-76607), negative geometry offsets (gh-75952), Variable lifetime (gh-123193), Tcl setting HOME on Windows (gh-71450), wm_manage with ttk widgets (gh-87577), default class bindings (gh-70273), and LC_NUMERIC’s effect on numeric widgets (gh-84008).

2. Test-coverage build-out — from large blind spots to real coverage

Much of tkinter had no automated tests, which is why so many of the fixes and API additions below were even possible to make safely. A systematic effort gave that surface real coverage (gh-151678, 17 commits; +4,400 lines across 52 commits overall). New test modules/suites were added for:

  • Widgets: Text, Menu, Listbox, Canvas, and the remaining widgets.
  • Submodules: tkinter.dnd (twice — general plus more), tkinter.filedialog, tkinter.scrolledtext, tkinter.simpledialog (including interactive tests), and tkinter.ttk methods.
  • Cross-cutting method groups: font, image and variable methods; the remaining Misc, Wm and geometry-manager methods; and widget virtual events.

Alongside coverage, the existing GUI tests were hardened (gh-69134): tests that depend on a mapped widget now wait until it is actually mapped (removing a class of flakiness), keyboard and virtual-event tests were made robust, and the suite was adapted to Tk 9.1 behaviour changes (gh-153380).

3. Modernized, themed dialogs

tkinter.simpledialog was rebuilt to match the look and feel of the native Tk dialogs (gh-59396, gh-151848):

  • SimpleDialog and the askinteger() / askfloat() / askstring() dialogs are now built from the themed tkinter.ttk widgets instead of the classic ones. The Dialog base class still defaults to classic widgets for compatibility, and both gained a use_ttk parameter to choose explicitly.
  • SimpleDialog gained bitmap and detail parameters, draws the standard icons with themed images, and accepts mappings of button options as buttons entries — an underline option adds an Alt accelerator.
  • Message font and wrap length now come from the Tk option database and can be overridden by the application.
  • The dialogs follow the Tk message-box keyboard conventions: the default ring follows keyboard focus, Return activates the focused button, and the OK/Cancel buttons gained Alt accelerators.

tkinter.filedialog was likewise switched to themed (ttk) widgets (gh-59396).

4. Broad new API — covering modern Tk (8.7 / 9.1)

A large batch of previously-unwrapped Tk commands became Python methods. The single biggest item is the enhanced ttk.Treeview (gh-151910): methods wrapping the Tk 9.1 ttk::treeview additions — item navigation and queries, opening, hiding, sorting and searching, and cell focus, selection and tagging — plus the Tk 9.0 detached query (with expand() / collapse() also working on older Tk). The rest, by area:

  • Window manager / info: Wm.wm_stackorder, Wm.wm_iconbadge, Misc.winfo_isdark (gh-151874); Misc.tk_scaling, Misc.tk_inactive, Menu.postcascade (gh-151881); Misc.tk_appname, Misc.tk_useinputmethods, Misc.tk_caret (gh-151886).
  • Canvas: rotate() and rchars() (gh-151876).
  • Text: sync() / pendingsync() (gh-151675); edit_canundo() / edit_canredo() (gh-151674).
  • Entry / Spinbox: validate methods (gh-151878).
  • PhotoImage: redither() (gh-151888) and more photo-image options across its methods (gh-151890).
  • ttk.Style: theme_styles() (gh-151920); OptionMenu accepts arbitrary Menubutton options (gh-101284).

5. font.Font can wrap a font description

tkinter.font.Font can now wrap an existing font description without creating a new named font — pass it as font with exists=True and no name (gh-143990). This avoids a loss of precision in actual(), measure() and metrics(), and keyword options now override the given font’s settings instead of being silently ignored.

6. Behaviour changes & deprecations

  • Boolean returns: winfo_exists, winfo_ismapped, winfo_viewable and Text.edit_modified now return a real bool instead of an integer or, depending on wantobjects, a string (gh-153422).
  • Deprecation: the Variable trace methods trace_variable, trace, trace_vdelete and trace_vinfo are now scheduled for removal in 3.17 (gh-127802).
  • Stricter variable API: the name parameter of wait_variable, setvar and getvar, and the value parameter of setvar, are now required (gh-152587).

7. Bug fixes

  • Crashes: non-BMP className with Tcl/Tk 8.x (gh-126219); Tcl interpreter deallocated on the wrong thread (gh-83274).
  • Leaks: memory leak in createcommand (gh-80937); reference leak in event bindings (gh-75666).
  • Correctness: nametowidget() with cloned menus (gh-38464); focus methods with non-tkinter widgets (gh-88758); consistent empty value from cancelled file dialogs (gh-103878); interactive tkinter with stdin redirected to a pipe on Windows (gh-140146).

Availability: the new API methods and themed dialogs are 3.16+; the enhanced ttk.Treeview requires Tk 9.1 (a few methods degrade gracefully on older Tk).

22 Likes