Why does tkinter (or turtle) seem to be missing or broken? Shouldn’t it be part of the standard library?

Question

WARNING: Do not use `pip` to try to solve the problem

The 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. I am currently attempting to get it delisted from PyPI.

Why some Python installations don’t include Tkinter components

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).

How to add Tkinter support, depending on the environment

See also:

Guide in the official Tk documentation: https://tkdocs.com/tutorial/install.html
Some previous (now duplicate) versions of the question with some useful answers:

Windows

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 .

Linux: Python that came with the Linux distribution

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.

Linux: Python built from source

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.

Brew (typically MacOS)

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

Headless environments

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).

Virtual environments

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.

Tkinter components

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? .)

WARNING: Do not use pip to try to solve the problem