Tk#

Tk is tkinter’s classic root window (tk.Tk), themed by ttkbootstrap and re-exported as ttk.Tk. It is the main window of an application and the top of the widget tree; creating it also starts the Tcl/Tk interpreter.

Prefer App

For applications, use App (also exported as Window) instead of ttk.Tk. App folds size, position, icon, and constraints into one constructor call and applies a theme for you, so you rarely call the raw window-manager methods below. Keep one root per program (the single-root rule); every other window is a Toplevel.

Options#

The root window takes the same surface options as a frame, plus a few of its own.

Option	Type	Description
`autostyle`	`bool`	Constructor only. `True` (default) applies the active theme; `False` opts out.
`menu`	`Menu`	The `Menu` widget to use as the window’s menu bar.
`screen`	`str`	Constructor only. The X display to open the window on.
`use`	`str`	Constructor only. The window id to embed this interpreter into.
`container`	`bool`	Constructor only. Make the window a container that another application can be embedded into. Rarely needed.
`background` (`bg`)	`str`	The fill color of the window.
`borderwidth` (`bd`)	`int`	The 3-D border width in pixels.
`relief`	`str`	The border style: `"flat"`, `"raised"`, `"sunken"`, `"groove"`, `"ridge"`, or `"solid"`.
`highlightthickness`	`int`	The width of the focus highlight around the window.
`highlightcolor`	`str`	The focus-highlight color when the window has focus.
`highlightbackground`	`str`	The focus-highlight color when the window does not have focus.
`padx`	`int`	Internal horizontal padding between the border and the content, in pixels.
`pady`	`int`	Internal vertical padding between the border and the content, in pixels.
`width`	`int`	The requested width in pixels. Usually set with `geometry()` instead.
`height`	`int`	The requested height in pixels. Usually set with `geometry()` instead.
`cursor`	`str`	The mouse cursor (see Cursors).
`takefocus`	`bool`	Whether the window accepts keyboard focus during traversal.
`class`	`str`	Constructor only. The widget class used for option-database lookups.
`visual`	`str`	Constructor only. The X visual. Rarely needed.
`colormap`	`str`	Constructor only. The X colormap. Rarely needed.

Window management#

As the application’s root window, Tk carries the full window-manager (wm) protocol below – the same surface a Toplevel has. The Windows guide teaches these by building.

Every window-manager method below is also available under its formal wm_-prefixed name (wm_title, wm_geometry, …); the short names are aliases.

Title, icon, and taskbar

title(string=None)

Set the window’s title-bar text, or return the current title when called with no argument.

Parameters:: string – the new title.
Returns:: the current title when queried, otherwise None.

iconphoto(default=False, *images)

Set the title-bar / taskbar icon from one or more PhotoImage objects (Tk picks the best size). Pass default=True to make it the default icon for this window and every toplevel created afterward.

Parameters:

default – make this the application-wide default icon.
images – one or more PhotoImage objects.

Returns:

None.

iconbitmap(bitmap=None, default=None)

Set the window icon from a bitmap. On Windows, default accepts a .ico path and applies it to this window and its future toplevels. Called with no argument, returns the current icon bitmap.

Parameters:

bitmap – the bitmap for this window.
default – (Windows) a .ico path applied as the default icon.

Returns:

the current bitmap when queried, otherwise None.

iconname(newName=None)

Set the name shown with the window’s icon (when minimized), or return it.

Returns:: the current icon name when queried, otherwise None.

iconmask(bitmap=None)

Set the mask bitmap that controls which pixels of the icon are drawn, or return the current mask.

Returns:: the current mask when queried, otherwise None.

iconposition(x=None, y=None)

Hint to the window manager where to place the window’s icon. Advisory — many window managers ignore it.

Returns:: None.

iconwindow(pathName=None)

Use another window as the icon for this one, or return the current icon window. Rarely supported on modern desktops.

Returns:: the current icon window when queried, otherwise None.

Size and position

geometry(newGeometry=None)

Set the window’s size and position as a "WxH+X+Y" string (any part may be omitted, e.g. "400x300" or "+100+100"), or return the current geometry.

Parameters:: newGeometry – a geometry string such as "640x480+200+120".
Returns:: the current geometry string when queried, otherwise None.

minsize(width=None, height=None)

Set the smallest size the user may resize the window to, or return the current minimum as (width, height).

Returns:: the current minimum when queried, otherwise None.

maxsize(width=None, height=None)

Set the largest size the user may resize the window to, or return the current maximum as (width, height).

Returns:: the current maximum when queried, otherwise None.

resizable(width=None, height=None)

Set whether the user may resize the window horizontally and vertically (two booleans), or return the current pair.

Parameters:

width – allow horizontal resizing.
height – allow vertical resizing.

Returns:

the current (width, height) flags when queried, otherwise None.

aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)

Constrain the window’s width-to-height ratio between minNumer/minDenom and maxNumer/maxDenom, or return the current constraint. Call with no arguments to clear it.

Returns:: the current aspect constraint when queried, otherwise None.

grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)

Ask the window manager to report and constrain the window’s size in grid units of widthInc × heightInc pixels (used by text-grid apps like a terminal), or return the current setting.

Returns:: the current grid setting when queried, otherwise None.

sizefrom(who=None)

Set who is considered to have specified the window’s size — "program" or "user" — or return the current value. Affects how the window manager treats the size.

Returns:: the current value when queried, otherwise None.

positionfrom(who=None)

Set who is considered to have specified the window’s position — "program" or "user" — or return the current value.

Returns:: the current value when queried, otherwise None.

State and visibility

deiconify()

Show the window, restoring it from a minimized or withdrawn state and raising it.

Returns:: None.

iconify()

Minimize the window to an icon.

Returns:: None.

withdraw()

Remove the window from the screen without destroying it (unmapped). Restore it with deiconify().

Returns:: None.

state(newstate=None)

Set the window state — "normal", "iconic" (minimized), "withdrawn", or "zoomed" (maximized, Windows/macOS) — or return the current state.

Returns:: the current state when queried, otherwise None.

overrideredirect(boolean=None)

Set whether the window manager ignores the window — a truthy value removes the border and title bar (a bare window, e.g. a splash) — or return the current flag. Ignored on macOS, where it destabilizes Tk.

Parameters:: boolean – True for a borderless window.
Returns:: the current flag when queried, otherwise None.

Attributes

attributes(*args)

Get or set platform window attributes. Call attributes("-alpha") to read one, or attributes("-alpha", 0.9) to set it. Common options:

-alpha — opacity, 0.0–1.0.
-topmost — keep above all other windows.
-fullscreen — fill the screen with no chrome.
-disabled — block input to the window.
-toolwindow — (Windows) a thin tool-window title bar, no taskbar entry.
-type — (X11) the window type, e.g. "dialog" or "splash".

Returns:: the requested attribute value when reading, otherwise None.

Relationships and protocols

protocol(name=None, func=None)

Register func as the handler for a window-manager protocol — most often "WM_DELETE_WINDOW" (the close button), letting you confirm or veto a close. Call with only name to return the current handler.

Parameters:

name – the protocol, e.g. "WM_DELETE_WINDOW" or "WM_TAKE_FOCUS".
func – the callback to run when the protocol fires.

Returns:

the current handler name when queried, otherwise None.

transient(master=None)

Mark the window as a transient of master — a dependent window (a dialog or picker) that stays above its owner and minimizes with it — or return the current master.

Parameters:: master – the owning window.
Returns:: the current master when queried, otherwise None.

group(pathName=None)

Add the window to the window group led by pathName so a window manager can treat the group as a unit, or return the current group leader.

Returns:: the current group leader when queried, otherwise None.

client(name=None)

Set the WM_CLIENT_MACHINE property (the host name the app runs on) for remote-display setups, or return it. X11 only.

Returns:: the current value when queried, otherwise None.

command(value=None)

Set the WM_COMMAND property — the command line that could restart the app, used by session managers — or return it. X11 only.

Returns:: the current value when queried, otherwise None.

colormapwindows(*wlist)

Set the WM_COLORMAP_WINDOWS list — the child windows whose colormaps the window manager should install — or return the current list. X11, rarely needed.

Returns:: the current list when queried, otherwise None.

focusmodel(model=None)

Set the window’s focus model — "active" or "passive" — or return it. Governs how the window accepts keyboard focus from the window manager.

Returns:: the current model when queried, otherwise None.

Embedding (advanced)

frame()

Return the platform window identifier of the outermost decorative frame the window manager drew around this window (or the window’s own id if none).

Returns:: a platform window id (a string).

manage(widget)

Turn a previously forget()-ten or embedded widget into a managed toplevel window.

Returns:: None.

forget(window)

Unmap a managed toplevel and hand it back to its parent’s geometry manager (the inverse of manage()).

Returns:: None.

Error handling#

report_callback_exception(exc, val, tb)

Called by tkinter whenever a callback raises an uncaught exception; the default prints the traceback to sys.stderr. Assign your own function (or override in a subclass) to log or display callback errors — see Handle errors gracefully.

Parameters:

exc – the exception class.
val – the exception instance.
tb – the traceback object.

Shared capabilities#

Tk also has the methods every widget inherits — configuration, event binding, lifecycle, focus, and introspection. These are documented under Capabilities.

Tk#

Options#

Window management#

Error handling#

Shared capabilities#

See also#