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.

Installing Tk

In this chapter, you'll get Tk installed on your machine, verify it works, and then see a quick example of what a Tk program looks like.

Though pretty much all macOS and Linux machines come with Tk installed already, it's often an older version (typically 8.4.x or an early 8.5). You want to make sure you've got at least version 8.5 (or possibly 8.6) to use the new widget set, so if that's not already there, you'll want to install the newer version.

Though there are lots of ways to install Tk, the easiest is to download and install one of the versions provided by ActiveState (www.activestate.com).

Users of recent Python versions can avoid this intermediate step, as starting with Python 3.7, the binary installers available at python.org now include everything you need to use Tk out of the box. If you're using an earlier Python version, or want to compile it yourself, you'll need to install Tcl/Tk on your system to do so. In this case, ActiveState's distribution would be the recommended way to go.

Note that this book assumes you're using Python 3, and not Python 2. There are some significant differences between the two, including module naming, which is the first thing you'll encounter when trying Tkinter.

ActiveState is a company that sells professional developer tools for dynamic languages. They also provide (for free) quality-controlled distributions of some of these languages, and happen to employ a number of core developers of these languages.

 

Installing Tk on macOS

On macOS, the easiest way to get Tk is to install the "ActiveTcl" distribution from ActiveState, which includes Tcl, Tk, plus a number of other extension libraries.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl, available as a universal binary. Make sure you're downloading an 8.6.x version, not an older version.

Run the installer to get everything loaded onto your machine. When you're done, you'll find a shiny new application called "Wish 8.6" inside the Utilities folder of your Applications folder. This is the "wish" shell, an application that includes both Tcl and Tk.

If you launch that application, you'll see two windows popup (see below), one titled "Wish" which will contain your application, and the second titled "Console" which is where you can type in Tcl/Tk commands.

screen shot
The Wish application running on macOS.

For convenient use from the Unix command line, you'll also find a script installed as /usr/local/bin/wish8.5 which will launch the same application.

To verify the exact version of Tcl/Tk that you are running, from the Wish console type the following:

% info patchlevel

We want this to be returning something like '8.6.9'.

While previous versions of macOS included both Ruby and Tk (albeit older 8.4 versions), since Snow Leopard this has no longer been the case.

RubyTk is a binding that links against an existing but separate Tk library. So, to get the latest version of Tk for Ruby, we're going to have to do two things, first download the latest 8.6.x Tcl/Tk version from ActiveState, and then compile (or re-compile) Ruby to use it.

Install ActiveTcl

The "ActiveTcl" distribution from ActiveState contains the latest Tk, as well as the latest version of Tcl (which Ruby's Tk bindings use internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl, available as a universal binary. Again, make sure you're downloading an 8.6.x version.

Run the installer and everything will be loaded onto your machine.

Compile Ruby

Make sure you've got Apple's developer tools (i.e. Xcode, which includes gcc and friends). Then if you haven't already got it, go to www.ruby-lang.org to download the latest stable (currently 2.6.x) version of Ruby.

Unpack it, and then from the Unix command line, run (note that the "configure" command should all be entered on one line, the <install-dir> should be replaced with the location you'd like your version of Ruby installed:

% ./configure --prefix=<install-dir>
		  --with-arch=x86_64,i386
		  --enable-pthread
		  --enable-shared
% make && make install

To verify that everything worked, start up your newly compiled copy of 'irb', and type:

% require 'tk'
% Tk::TK_PATCHLEVEL

The first line should load RubyTk; typically if there was a problem with compiling it would show up here. The second line will return the version of Tk that you're running, which should be something like "8.5.18".

Verified steps using ActiveTcl 8.5.18.0, Ruby 2.2.2, and Mac OS X 10.10.3.

For modern Tk programming using Perl, the "Tkx" module is highly recommended, and we'll be using that here. The easiest way to get set up is to use the "ActivePerl" distribution from www.activestate.com.

Install ActivePerl >= 5.10

The "ActivePerl" distribution from ActiveState includes not only Perl, but also recent versions of Tk and Tcl (which Tkx uses internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePerl, available as a universal binary.

Run the installer and everything will be loaded onto your machine. Note that ActivePerl will be installed in /usr/local/ActivePerl-5.x (where 'x' is the actual version, e.g. '14').

To find out what version of Tk Perl and Tkx are using, run this from the Unix command line:

% /usr/local/ActivePerl-5.14/bin/perl -MTkx -e 'print Tkx::info("patchlevel");'

We want this to be returning something like "8.5.9".

Versions of ActivePerl prior to 5.10 (and some of the first 5.10 builds) included earlier versions of Tcl/Tk (8.4.x rather than 8.5.x). We therefore very highly recommend upgrading to at least ActivePerl 5.10, and verify that you do have Tk 8.5 or newer.

Verified install using ActivePerl 5.14.2 on Mac OS X 10.7.2.

As noted, the easiest way to get Tk and Tkinter installed on your system is using Python's binary installer, available at python.org. Thanks to work by Python core developer Ned Deily, binary installers starting with version 3.7 include Tcl and Tk.

Remember, we're using Python 3.x here, not 2.x. As of this writing, the latest 3.7 installer (3.7.3) includes Tk 8.6.8.

If, however, you're compiling Python yourself, you'll have more work to do. Read on...

Installing Tcl/Tk and Compiling Python

Tkinter is included with core Python of course, but you'll need a version of Tcl/Tk on your system to compile it against. Do yourself a huge favour and get the most recent version.

Whatever you do, do not rely on the Tk versions included in macOS! Older versions included Tk 8.4.x. Even more recent macOS versions include an early 8.5 version (8.5.9, released in 2010), which has several serious bugs that are easily triggered by Tkinter.

While there are several different ways to get Tcl and Tk onto your machine, the easiest and most recommended is to use the ActiveTcl distribution.

In your web browser, visit www.activestate.com/products/activetcl. Download ActiveTcl (as of this writing it's labelled version 8.6.8, though is actually 8.6.9). Make sure to download an 8.6.x version, not something older! Note that you will need to create an account with ActiveState (no cost) to download this distribution. After it's downloaded, run the installer to get Tcl and Tk loaded onto your machine.

If you're a masochist and want to read about other Tcl/Tk options and variations and how they interact with Python, see the Mac Tcl/Tk page at python.org. If you want to compile Tcl/Tk from source, see www.tcl.tk.

When compiling Python from source, you need to tell it where to find the ActiveTcl (or other) distribution. Otherwise, it won't find any Tcl/Tk distribution (so Tkinter won't work), or it will find the (ancient and broken) version of Tcl/Tk that is supplied with macOS.

When doing the initial "./configure," in the Python build process, you will need to add two new options, specifying the paths (one for Tcl, one for Tk; note the location of the single quotes in the example below) to the include files, and also the locations of the Tcl and Tk libraries. For example:

% ./configure --with-tcltk-includes=‘-I/Library/Frameworks/Tcl.framework/Headers 
             -I/Library/Frameworks/Tk.framework/Headers' 
       --with-tcltk-libs=‘/Library/Frameworks/Tcl.framework/Versions/8.6/Tcl 
             /Library/Frameworks/Tk.framework/Versions/8.6/Tk’

The initial '%' is the Unix shell prompt, you don't have to type it. The rest of it should all go on one line, without adding line breaks.

When everything is built, be sure to test it out. Start Python from your terminal, e.g.

% ./python.exe

This should give you the Python command prompt. From the prompt, enter these two commands:

>>> import tkinter
>>> tkinter._test()

This should pop up a small window; the first line at the top of the window should say "This is Tcl/Tk version 8.6"; make sure it is not 8.4 or 8.5!

Get an error saying "No module named tkinter?" You're probably using Python 2. This tutorial assumes Python 3.

You can also get the exact version of Tcl/Tk that is being used with:

>>> tkinter.Tcl().eval('info patchlevel')

which should return something like '8.6.9'.

Verified install using ActiveTcl 8.6.9 and Python 3.7.3 source code from python.org on macOS 10.13.6.

 

Installing Tk on Windows

On Windows, the easiest way to get Tcl/Tk onto your machine is to install the "ActiveTcl" distribution from ActiveState, which includes Tcl, Tk, plus a number of other extension libraries.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl for Windows. Make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Run the installer, and follow along. You'll end up with a fresh install of ActiveTcl, usually located in C:\Tcl. From a DOS command prompt, or the Start Menu's "Run..." command, you should then be able to run a Tcl/Tk 8.5 shell via:

% C:\Tcl\bin\wish85

This should pop up a small window titled "wish85", which will contain your application. A second, larger window titled "Console" is where you can type in Tcl/Tk commands. To verify the exact version of Tcl/Tk that you are running, type the following:

% info patchlevel

We want this to be returning something like '8.5.10'.

Type "exit" in the console window to exit. You may also want to add C:\Tcl\bin to your PATH environment variable.

Verified install using ActiveTcl 8.5.10.1 on Windows 7.

RubyTk is the binding for Tk. Installing it on your Windows machine used to be pure hell, involving installing a separate version of Tcl/Tk, downloading a development environment like Visual Studio, downloading the Ruby source code, carefully compiling Ruby, ...

Luckily, it is (since July 2011) now remarkably easy, because the good RubyInstaller for Windows people now include Tk 8.5 as part of their excellent and easy to use installer. Thanks very much!

So all you'll need to do is download and run RubyInstaller, making sure to check the option in the installer to include Tcl/Tk support. This will install everything into the directory you choose, e.g. "C:\Ruby192".

To verify the version of Tk, start up your newly installed copy of 'irb' (which would have been installed in e.g. "C:\Ruby192\bin"), and type:

% require 'tk'
% Tk::TK_PATCHLEVEL

The first line should load RubyTk. The second line will return the version of Tk that you're running, which should be something like "8.5.10".

Verified install using RubyInstaller 1.9.2-p290 on Windows 7.

For modern Tk programming using Perl, the "Tkx" module is highly recommended, and we'll be using that here. The easiest way to get set up is to use the "ActivePerl" distribution from www.activestate.com.

Install ActivePerl >= 5.10

The "ActivePerl" distribution from ActiveState includes not only Perl, but also recent versions of Tk and Tcl (which Tkx uses internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePerl.

Run the installer and everything will be loaded onto your machine. On our machine, perl.exe was installed at "C:\perlin"

To find out what version of Tk Perl and Tkx are using, run this from the Windows command prompt:

% perl -MTkx -e "print Tkx::info("patchlevel");"

We want this to be returning something like "8.5.9".

Versions of ActivePerl prior to 5.10 (and some of the first 5.10 builds) included earlier versions of Tcl/Tk (8.4.x rather than 8.5.x). We therefore very highly recommend upgrading to at least ActivePerl 5.10, and verify that you do have Tk 8.5 or newer.

Verified install using ActivePerl 5.12.4 on Windows 7.

Tkinter (and, since Python 3.1, ttk) is included in the Python standard library. We highly recommend installing Python using the standard binary distributions from python.org. These will automatically install Tcl/Tk, which of course is needed by Tkinter.

If you're instead building Python from source code, the Visual Studio projects included in the PCbuild directory can automatically fetch and compile Tcl/Tk on your system.

Once you've installed or compiled, test it out to make sure it works. From the Python prompt, enter these two commands:

>>> import tkinter
>>> tkinter._test()

This should pop up a small window; the first line at the top of the window should say "This is Tcl/Tk version 8.6"; make sure it is not 8.4 or 8.5!

Get an error saying "No module named tkinter?" You're probably using Python 2. This tutorial assumes Python 3.

You can also get the exact version of Tcl/Tk that is being used with:

>>> tkinter.Tcl().eval('info patchlevel')

which should return something like '8.6.9'.

Verified using Python 3.7.3 binary installer from python.org (containing Tcl/Tk 8.6.9) on Windows 10.0.

 

Installing Tk on Linux

While Linux distributions pretty much all come with Tcl/Tk installed, most include Tk 8.4.x, and we want to make sure to get an 8.5.x version. The easiest way to do this is to install the "ActiveTcl" distribution from ActiveState, which includes Tcl, Tk, plus a number of other extension libraries.

In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl for Linux. Make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Unpack it, and run the installer (sudo ./install.sh), and follow along. You'll end up with a fresh install of ActiveTcl, located in /opt/ActiveTcl-8.5. You should then be able to run a Tcl/Tk 8.5 shell via:

% /opt/ActiveTcl-8.5/bin/wish8.5

This should pop up a window titled "wish8.5". To verify the exact version of Tcl/Tk that you are running, from the Wish prompt (in the terminal window) type the following:

	% info patchlevel

We want this to be returning something like '8.5.10'. Type a control-D at the prompt in the terminal window to exit. You may also want to add /opt/ActiveTcl-8.5/bin to your Unix path.

Verified install using ActiveTcl 8.5.10.1 on Ubuntu 11.04.

While Linux distributions pretty much all come with both Tk and Ruby installed, one of them (or the connection between them) is usually very out of date.

RubyTk is a binding that links against an existing but separate Tk library. So, to get the latest version of Tk for Ruby, we're going to have to do two things, first download the latest 8.5.x Tcl/Tk version from ActiveState, and then compile Ruby to use it.

Okay, you might get lucky and find that there is a package for your Linux distribution that lets you use a relatively recent Ruby with a relatively recent Tk. If you go this route, just make sure it's at least Tk 8.5!

Install ActiveTcl

The "ActiveTcl" distribution from ActiveState contains the latest Tk, as well as the latest version of Tcl (which Ruby's Tk bindings use internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActiveTcl for Linux. Again, make sure you're downloading an 8.5.x version, not an older 8.4.x version.

Unpack it, and run the installer (install.sh), and follow along. You'll end up with a fresh install of ActiveTcl, located in /opt/ActiveTcl-8.5.

Setup your Development Environment

You'll need to make sure you have a fairly robust development environment on your machine. Besides the usual gcc and friends, make sure that you've got the X11 development files (e.g. all the include files; on Ubuntu there were included in the "libx11-dev" package).

Really, you need the X11 development files to compile, even though ActiveTcl is prebuilt and so doesn't need them. I wasted hours on this playing with various options, because the error messages if the headers aren't there are either missing or misleading.

Compile Ruby

Next, go to www.ruby-lang.org to download the latest stable (currently 1.9.x) version of Ruby.

Unpack it, and then from the Unix command line, run (note that the <install-dir> should be replaced with the location you'd like your version of Ruby installed):

% ./configure --prefix=<install-dir> && make && make install

This should locate the copy of ActiveTcl that you installed. To verify that everything worked, start up your newly compiled copy of 'irb', and type:

% require 'tk'
% Tk::TK_PATCHLEVEL

The first line should load RubyTk; typically if there was a problem with compiling it would show up here. The second line will return the version of Tk that you're running, which should be something like "8.5.10".

Verified install using ActiveTcl 8.5.10.1, Ruby 1.9.3-p0 on Ubuntu 11.04.

For modern Tk programming using Perl, the "Tkx" module is highly recommended, and we'll be using that here. The easiest way to get set up is to use the "ActivePerl" distribution from www.activestate.com.

Install ActivePerl >= 5.10

The "ActivePerl" distribution from ActiveState includes not only Perl, but also recent versions of Tk and Tcl (which Tkx uses internally to talk to Tk). In your web browser, go to www.activestate.com, and follow along the links to download the Community Edition of ActivePerl.

Run the installer and everything will be loaded onto your machine, in e.g. /opt/ActivePerl-5.12.

To find out what version of Tk Perl and Tkx are using, run this from the command line:

% perl -MTkx -e 'print Tkx::info("patchlevel");'

We want this to be returning something like "8.5.9".

Versions of ActivePerl prior to 5.10 (and some of the first 5.10 builds) included earlier versions of Tcl/Tk (8.4.x rather than 8.5.x). We therefore very highly recommend upgrading to at least ActivePerl 5.10, and verify that you do have Tk 8.5 or newer.Verified install using ActivePerl 5.12.4 on Ubuntu 11.04.

Tkinter (and, since Python 3.1, ttk) is included in the Python standard library. It relies on Tcl/Tk being installed on your system. Depending on how you install Python, this may not happen automatically.

Remember, we're using Python 3.x here, not 2.x.

You have several different options to get Python and Tkinter onto your machine. We'll show you two, using your distro's package manager, or compiling from source.

Option 1. Your Linux Distribution's Package Manager

Currently supported Linux distributions will usually already include a recent version of Python 3.x (or have a .deb, .rpm, etc. package available to install). If so, this is usually the easiest way to go.

However, after you're done, start up a Python shell (e.g. /usr/bin/python3) and verify the install (see below). You may find that when you try to 'import tkinter' that you get an error. Sometimes it will tell you that you need to install another package. If so, follow the instructions, and try again. It may also just give you Python's standard error message: ModuleNotFoundError: No module named 'tkinter'.

If you're getting an error saying "No module named tkinter" (without the single quotes around the module name), you're probably using Python 2. This tutorial assumes Python 3.

For example, running Ubuntu 19.04, Python 3.7.3 is already installed. However, you also need to install a separate package, python3-tk, to use Tkinter, e.g.

% sudo apt-get install python3-tk

In this case, that package provides Tcl/Tk 8.6.9 libraries to be used with Python.

Option 2. Install Tcl/Tk and Compile the Standard Python Distribution

If you'd like to use the standard source distribution from python.org, you can certainly do that.

But to do so, you'll need to get the Tcl and Tk include files and libraries loaded on your machine first. While there are again several ways to do that, the easiest is to download and install ActiveTcl.

In your web browser, go to www.activestate.com/products/activetcl. Download the latest version of ActiveTcl for Linux. Make sure you're downloading an 8.6 or newer version. Note that you will need to create an account with ActiveState (no cost) to download this distribution. After it's downloaded, unpack it, run the installer (sudo ./install.sh), and follow along. You'll end up with a fresh install of ActiveTcl, located in e.g. /opt/ActiveTcl-8.6.

Next, download the current Python 3.x source distribution from python.org, and unpack it. On your configure line, you'll need to tell it how to find the version of Tcl/Tk you installed. Then build as usual:

% ./configure --with-tcltk-includes='-I/opt/ActiveTcl-8.6/include' 
       --with-tcltk-libs='/opt/ActiveTcl-8.6/lib/libtcl8.6.so /opt/ActiveTcl-8.6/lib/libtk8.6.so'
% make
% make install

Make sure to verify your install (see below).

Didn't work? There may have been an error compiling Python's tkinter code. To check, from the main Python source directory, try "touch Modules/_tkinter.c" (note the underscore) and then "make" to recompile it. Watch closely for error messages.
 
The most common thing is that the way you specified the Tcl/Tk include and libraries needs to be changed somehow. Or if you get messages that certain include files can't be found (e.g. "X11/Xlib.h") you may need to install additional packages on your Linux distribution (e.g. "apt-get install libx11-dev"). Once you get it to compile without errors, don't forget to "make install".

Verifying your Install

At the Python command prompt, enter these two commands:

>>> import tkinter
>>> tkinter._test()

This should pop up a small window; the first line at the top of the window should say "This is Tcl/Tk version 8.6"; make sure it is not 8.4!

If it gives you an error when you try to 'import tkinter' (e.g. "If this fails your Python may not be configured for Tk"), something hasn't been set up right. If you compiled Python yourself, see above to check for compile errors.

Get an error saying "No module named tkinter?" You're probably using Python 2. This tutorial assumes Python 3.

You can also get the exact version of Tcl/Tk that is being used with:

>>> tkinter.Tcl().eval('info patchlevel')

which should return something like '8.6.9'.

 

The Obligatory First Program

To make sure that everything actually did work, let's try to run a "Hello World" program in Tk. While for something this short you could just type it in directly to the interpreter, instead use your favorite text editor to put it in a file.

package require Tk
grid [ttk::button .b -text "Hello World"] 

Save this to a file named 'hello.tcl'. From the wish shell, type:

% source hello.tcl

Couldn't find hello.tcl? You might be looking in the wrong directory. You can either give the full path to hello.tcl, or use Tcl's "pwd" and "cd" commands to see what directory you're in, and change to a different one.

require 'tk'
require 'tkextlib/tile'
root = TkRoot.new() 
button = Tk::Tile::TButton.new(root) {text "Hello World"}.grid
Tk.mainloop()

Save this to a file named 'hello.rb'. Start up 'irb', and from the command prompt, type:

% source "hello.rb"

Couldn't find hello.rb? You might be looking in the wrong directory. You can either give the full path to hello.rb, or use Ruby's "Dir.pwd" and "Dir.chdir" commands to see what directory you're in, and change to a different one.

use Tkx;
Tkx::grid( Tkx::ttk__button(".b", -text => "Hello, world" ) );
Tkx::MainLoop();

Note that there are two underscores between "ttk" and "button".

Save this to a file named 'hello.pl'. From a command prompt, type:

% perl hello.pl

Couldn't find hello.pl? You might be looking in the wrong directory. Try providing the full path to hello.pl.

Not working? Are you sure you're using an 8.5.x version of Tcl/Tk? See the install chapter...

from tkinter import *
from tkinter import ttk
root = Tk()
ttk.Button(root, text="Hello World").grid()
root.mainloop()

Save this to a file named 'hello.py'. From a command prompt, type:

% python hello.py

Couldn't find hello.py? You might be looking in the wrong directory. Try providing the full path to hello.py.

screen shot
Our First Program. Some work left to do before the IPO.