I have seen many different things go wrong when trying to use the Tkinter standard library package, or its related functionality (turtle graphics using turtle
and the built-in IDLE IDE), or with third-party libraries that have this as a dependency (e.g. displaying graphical windows with Matplotlib).
It seems that even when there isn't a problem caused by shadowing the name of the standard library modules (this is a common problem for beginners trying to follow a tutorial and use turtle graphics - example 1; example 2; example 3; example 4), it commonly happens that the standard library Tkinter just doesn't work. This is a big problem because, again, a lot of beginners try to follow tutorials that use turtle graphics and blindly assume that the turtle
standard library will be present.
The error might be reported:
As ModuleNotFoundError: No module named 'tkinter'
; or an ImportError
with the same message; or with different casing (I am aware that the name changed from Tkinter
in 2.x to tkinter
in 3.x; that is a different problem).
Similarly, but referring to an internal _tkinter
module, and displaying code with a comment that says "If this fails your Python may not be configured for Tk"; or with a custom error message that says "please install the python-tk package" or similar.
As "No module named turtle" when trying to use turtle
specifically, or one of the above errors.
When trying to display a plot using Matplotlib; commonly, this will happen after trying to change the backend, which was set by default to avoid trying to use Tkinter.
Why do problems like this occur, when Tkinter is documented as being part of the standard library? How can I add or repair the missing standard library functionality? Are there any special concerns for specific Python environments?
See also: "UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure." when plotting figure with pyplot on Pycharm . It is possible to use other GUI backends with Matplotlib to display graphs; but if the TkAgg
backend does not work, that is because of a missing or faulty Tkinter install.
In Python 3.x, the name of the Tkinter standard library module was corrected from Tkinter
to tkinter
(i.e., all lowercase) in order to maintain consistent naming conventions. Please use Difference between tkinter and Tkinter to close duplicate questions caused by trying to use the old name in 3.x (or the new name in 2.x). This question is about cases where Tkinter is not actually available. If it isn't clear which case applies, please either offer both duplicate links, or close the question as "needs debugging details".
pip
to try to solve the problemThe Pip package manager cannot help to solve the problem. No part of the Python standard library - including tkinter
, turtle
etc. - can be installed from PyPI. For security reasons, PyPI now blocks packages using names that match the standard library.
There are many packages on PyPI that may look suitable, but are not. Most are simply wrappers that try to add a little functionality to the standard library Tkinter. However, one especially problematic package is turtle
. It should not be there, because current policy (since 2017) is to block packages with names that match the standard library; but it was uploaded long before that, and has not been maintained since. It is Python 2.x specific code that will break during installation on Python 3, is extremely out of date (published in 2009) and - most importantly - has nothing whatsoever to do with turtle graphics.
Shortly before the original draft of this Q&A, I put in a request to get the turtle
package delisted from PyPI. As of this update (over a year later), it appears that something may soon be done about it.
There are several reasons why Tkinter might be missing, depending on the platform (although generally, the motivation is probably just to save space).
When Python is installed on Windows using the official installer, there is an option to include or exclude Tcl/Tk support.
Python installations that come pre-installed with Linux may exclude Tkinter, or various components, according to the distro maintainer's policy. For example, the Python that came with my copy of Linux included the turtle
standard library, but not the underlying Tkinter package:
>>> import turtle
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/usr/lib/python3.8/turtle.py", line 107, in <module>
import tkinter as TK
ModuleNotFoundError: No module named 'tkinter'
Other builds might not include the turtle
module either.
Python built from source might be missing Tkinter support because of deliberately chosen configuration options, or because dependencies were missing before starting compilation.
Note that virtual environments will generally have the same Tkinter support as the Python installation they're based upon. However, adding Tkinter support to the base might not update the virtual environment. In this case, it will be necessary to re-create the virtual environment from scratch. It is not possible to add or remove Tkinter support for an individual virtual environment. This is because a virtual environment only differs from its base in terms of the site packages, and there is no site package for Tkinter (since, again, it is a standard library component that cannot be obtained using Pip).
See also:
For Python installed using the official installer from python.org, use the operating system features to choose to "repair" the installation (or, if acceptable, uninstall and reinstall Python). This time, make sure to check the option to install the "tcl/tk and IDLE" optional feature.
Some legacy setups may have had issues with conflicts between 32- and 64-bit versions of Python and Tcl/Tk. This should not cause problems on new setups.
For the embeddable zip package, see Python embeddable zip: install Tkinter .
If the Python that came with your Linux distribution doesn't include Tkinter, consider leaving that alone and installing a separate version of Python - just on general principle. However, in general, Tkinter support can be added to the system Python using the system package manager (not Pip).
It will typically be necessary to use sudo
(not included in examples here) to make such changes to the system Python.
On Ubuntu and Debian based systems (including Pop!_OS, Ubuntu-based Mint): use apt-get install python3-tk
, assuming the system Python is a 3.x version. For 2.x legacy systems, use apt-get install python-tk
instead. In some cases it may be necessary to specify a minor version, like apt-get install python3.11-tk
. In some cases, a custom exception message may say to install python-tk
even though python3-tk
should actually be installed instead.
For Fedora, use dnf install python3-tkinter
, as described by d-coder here.
For Arch, use pacman -S tk
, as described by Jabba here.
For RHEL, use yum install python3-tkinter
, as described by amzy-0 here.
The above packages can only add Tkinter support to the system python (the one installed in /usr/bin
, which is used by the operating system to run essential scripts). They cannot add Tkinter support to a separate Python built from source. This is because, in addition to the actual Tcl/Tk library, using Tkinter in Python requires a per-installation "binding" library (referred to as _tkinter
in the Python source code). System packages will not add this library to other Python installations.
Therefore, install a development Tk package first (e.g. apt-get install tk-dev
) and try rebuilding.
See also:
Unable to install tkinter with pyenv Pythons on MacOS (using pyenv
)
Install tkinter and python locally (in case sudo
privileges are not available)
Building Python and more on missing modules (more generally about rebuilding Python from source and filling in development dependencies)
Use brew install python-tk
; if necessary, specify a Python version like brew install [email protected]
.
For non-system installations, it may be necessary to re-install and specify that Tkinter support should be included, like brew install python --with-tcl-tk
. See also: Why does Python installed via Homebrew not include Tkinter
It's generally not possible to install Tkinter - or any other GUI toolkit - for headless server environments like PythonAnywhere or Amazon Linux EC2. The code will run on a remote server, so there is no monitor to display the GUI; while it would be possible in principle for the code to send commands back to the client that the client could then use to create a GUI, in general the server will have no knowledge of the client's environment. Making this work would require setting up some communication protocol ahead of time (such as X11).
First, fix the installation that the virtual environment is based upon. If this doesn't resolve the problem, re-create the virtual environment (and reinstall everything that was installed in the old virtual environment). Unfortunately, there is not a clean way around this. It might be possible to patch around the problem by changing a bunch of symlinks, but this is not supported.
If it is not possible to fix the base installation (for example, due to not having sudo
rights on the system), consider installing a separate Python (for example, by compiling from source), ensuring that it is installed with Tkinter support, and creating virtual environments from that Python.
Additional hints: TKinter in a Virtualenv
Some users will find it useful to understand exactly what the Tkinter system contains. There are several components:
The underlying Tcl/Tk library, written in C. Some systems may independently have a Tcl/Tk installation that is unusable from Python by default.
The _tkinter
implementation module, which is also written in C and which interfaces between Python and Tcl/Tk ("tkinter" means "Tk interface"). This is an implementation detail, and should not be imported directly in Python user code. (the C code for this dates all the way back to 1994!)
The tkinter
package itself, which provides wrappers for the lower-level _tkinter
interface, as well as ttk
(a separate interface for newer "themed" widgets).
Higher-level components, such as IDLE and turtle
.
Any given installation could theoretically be missing any or all of these components. For system installations of Python on Linux and MacOS, the distro maintainer is responsible for making sure that the appropriate package (python3-tk
or similar) installs whichever parts are missing by default, to the appropriate places.
As explained to me on GitHub by Terry Jan Reedy: when the Windows installer is told to install Tcl/Tk, it will install a separate copy of that library (and the corresponding _tkinter
and tkinter
etc.) for that Python installation. On Linux, Tcl/Tk will normally come with Linux; packages like python3-tk
will add a _tkinter
that uses the system Tcl/Tk, and a tkinter
package (which will naturally find and use the _tkinter
implementation, using the normal import mechanism).
Since the Tcl/Tk installation is thus "vendored" for Windows, the Tcl/Tk version will depend on the Python version. On Linux it will depend on the system, and it should be possible to use the system package manager to upgrade Tcl/Tk independently of Python. Note in particular that newer versions of Python might not be able to work with an outdated system Tcl/Tk. (To check the Tcl/Tk version for a working installation, see How to determine what version of python3 tkinter is installed on my linux machine? .)