Modern Tkinter

Modern Tkinter ebook

Want TkDocs to go? If you've found the material on this site useful, please consider buying this book, which is based on the Python material in the tutorial.

Mark Roseman

p.s. your purchase helps me improve this site... thank you!


Only $10 for e-book. pick your format:

Paperback PDF Kindle Apple Books B&N Nook Kobo

(Slightly more for paperback. Also available on other e-book platforms.)

This tutorial will quickly get you up and running with the latest Tk from Tcl, Ruby, Perl or Python on Mac, Windows or Linux. It provides all the essentials about core Tk concepts, the various widgets, layout, events and more that you need for your application.


This tutorial is designed to help people get up to speed quickly with building mainstream desktop graphical user interfaces with Tk, and in particular Tk 8.5 and 8.6. Tk 8.5 was an incredibly significant milestone release and a significant departure from the older versions of Tk which most people know and love recognize.

The downside is that unless you know one or two particular things, it's actually not that significant a release; For backwards compatibility reasons, unless existing programs make a few simple changes, they won't look all that much different. So while this tutorial will certainly benefit newcomers to Tk, it will also help existing Tk developers bring their knowledge right up to date. It's a cliche, but I can't believe how much I've learned in writing this tutorial, and I've been using Tk for over twenty-five years.

The general state of Tk documentation (outside the Tcl-oriented reference documentation, which is excellent) is unfortunately not at a high point these days. This is particularly true for developers using Tk from languages other than Tcl, and developers working on multiple platforms.

So this tutorial will, as much as possible, target developers on the three main platforms (Windows, Mac, Linux), and also be language-neutral. Initially, the tutorial will cover Tcl, Ruby, Perl and Python. Over time, additional languages may be added. Even if your own language isn't included, the chances are you'll still benefit; since all the languages use the same underlying Tk library, there's obviously a lot of overlap.

This is also not a reference guide, it's not going to cover everything, just the essentials you need in 95% of applications. The rest you can find in reference documentation.


Who this Tutorial is for

This tutorial is designed for developers building tools and applications in Tk. It's also concerned with fairly mainstream graphical user interfaces, with buttons, lists, checkboxes, rich text editing, 2D graphics and so on. So if you're either looking to hack on Tk's internal C code, or build the next great 3D immersive game interface, this is probably not the material for you.

This tutorial also doesn't teach you the underlying programming language (Tcl, Ruby, Perl, Python, etc.), so you should have a basic grasp on that already. Similarly, you should have a basic familiarity with desktop applications in general, and while you don't have to be a user interface designer, some appreciation of GUI design is always helpful.


Modern Best Practices

This tutorial is all about building modern Tk user interfaces using the current tools Tk has to offer. It's all about the best practices you need to know to do this.

For most tools, you wouldn't think you'd have to say something like that, but for Tk, that's not the case. Tk has had a very long evolution (see Tk Backgrounder), and any evolution tends to leave you with a bit of cruft. Couple that with how much graphical user interface platforms and standards have evolved in that time, and you can see where keeping something as large and complex as a GUI library up to date as well as backwards compatible may be challenging.

Tk has, for most of its lifetime, gotten a bad rap, to put it mildly. Some of this has been well deserved, most of it not so much. Like any GUI tool, it can be used to create absolutely terrible looking and outdated user interfaces, but with the proper care and attention, it can also be used to create spectacularly good ones as well. Most people know about the crappy ones; most of the good ones people don't even know are done in Tk. In this tutorial, we're going to focus on what you need to build good user interfaces, which isn't nearly as hard as it used to be before Tk 8.5.

So modern desktop graphical user interfaces, using modern conventions and design sense, using the modern tools provided by Tk 8.5 and 8.6.

Tk Extensions

When it comes to modern best practices, Tk extensions deserve a special word of note. Over the years, a number of groups have provided all kinds of add-ons to Tk, for example adding new widgets not available in the core (or at least not at the time). Some well-known and quite popular Tk extensions include BLT, Tix, iWidgets, BWidgets; there are many, many others.

Many of these extensions were created decades ago. Because core Tk has always been highly backwards compatible, these extensions generally continue to work with newer versions. However, many have not been updated, or not been significantly updated, in a long time. They may not reflect current platform conventions or styles, and so while they "work", they can make your application appear extremely dated or out of place.

If you do decide to use Tk extensions, it's highly recommended that you investigate and review your choices carefully.


The Better Way Forward

Tk also gives you a lot of choices. There are at least six different ways to layout widgets on the screen, often multiple different widgets that could accomplish the same thing, especially if you count the huge assortment of Tk extensions like Tix, BLT, BWidgets, Itk and others. Most of these also are older, most not updated and therefore crappy looking, and in many cases, the facilities they provide have been obsoleted by newer and more modern facilities recently built into Tk itself. But for backwards compatibility reasons, most of these old ways of doing things still keep working, year after year. That doesn't necessarily mean people should still be using some of them.

So there are a lot of choices in Tk, but frankly, all that choice gets in the way. If you want to learn and use Tk, you don't need all the choices, you need the right choice, so you don't have to do all the research and make that choice yourself. That's what this tutorial will give you. Think of it as the documentation equivalent of opinionated software. So we'll often use different ways of doing things than in other documentation or examples; often, it's because when those were written, the better ways didn't even exist yet. Later on, once you're an expert, and you're encountering some wacky situation where the normal choice doesn't fit, you can go hunt around for alternatives.


How to Use

While the tutorial is designed to be used linearly, feel free to jump around as you see fit. We'll often provide links where you can go for more information, whether links to other documentation on this site, such as our "widget roundup" providing usage info on each Tk widget, or to external documentation, such as the full reference for a particular command.

The tutorial also lets you select what language (Tcl, Ruby, Perl or Python) to show. You can change this by the "Show:" popup menu which is located in the sidebar, near the top right of each page in the tutorial. But it also lets you see how Tk is used by all the different languages, which can itself be quite interesting and useful.

You can find a GitHub repository containing many of the larger examples at


As is typically done, code listings, interpreter or shell commands and responses will be indicated with a fixed-width font. When showing an interactive session with the interpreter, the parts that you enter will additionally be in bold fixed-width.

When describing procedure or method calls, the literal parts (e.g. the method name) will be in a plain fixed-width font, parameters where you should fill in the actual value will add italics, and optional parameters will be surrounded by '?', e.g. "set variable ?value?".

You'll see some paragraphs that are separated from the main text. These are used for several different things. Each is identified with a different icon, as follows:

This paragraph consists of material that is specific to the Tcl binding to Tk.

This paragraph consists of material that is specific to the Ruby binding to Tk.

This paragraph consists of material that is specific to the Perl binding to Tk.

This paragraph consists of material that is specific to the Python binding to Tk.

This paragraph will help point out common mistakes that people make or suggest useful but not necessarily obvious solutions related to the topic.

This indicates a new way of doing things in Tk 8.5 or Tk 8.6 that is very different from the way things would have been done previously. People familiar with older versions of Tk, or working on programs developed with older versions of Tk, should pay close attention.

This paragraph provides some additional background information, not strictly necessary to understanding the topic at hand, but that might help you understand a bit more about how or why things are done the way they are.

This indicates some error in the tutorial itself which hasn't yet been corrected, or a section that has been deleted but not yet replaced.

This indicates an area in Tk that could most charitably be described as a "rough edge." It may indicate a bad or missing API requiring you to use a workaround in your code. Because these things tend to get fixed up over time, it's worth marking them in your code with a "TODO" so you can remember to go back later and see if a newer API resolves the problem cleanly.