Post History

## General

This question and answer are adapted from [my original write-up on Stack Overflow](https://stackoverflow.com/questions/76105218), which you may consult for more details. This version is crafted as to be a clear overview, without referring to a huge pile of previous Q&A about specific special circumstances. You may also be interested in the [guide provided by the official Tk documentation](https://tkdocs.com/tutorial/install.html).

The short explanation: Although Tkinter is indeed part of the standard library, several distributions deliberately exclude it. It may also be broken due to missing system support. See the appropriate section below to find out how to add Tkinter support for your system.

<section class="notice is-danger">

**Do not use `pip` to try to solve the problem. The Pip package manager cannot help here. 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](https://github.com/pypi/warehouse/issues/2151); 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 have an [outstanding support ticket](https://github.com/pypi/support/issues/2771) to try to get it delisted from PyPI.
</section>

### If IDLE seems to be missing but `tkinter` works properly

Try `python -m idlelib` to run IDLE directly from Python. There might just not be a wrapper provided for this (or it might not be on the `PATH` for some reason).

## Linux

<details>

### Using the system-provided Python

`tkinter` is often deliberately excluded (perhaps just to save space). The downstream components (IDLE and `turtle`) may also be excluded, or they might just fail at runtime.

Use the system package manager to install Python tkinter library support. Examples:

```
# Debian/Ubuntu (and Mint, Pop! OS etc.)
apt-get install python3-tk
# (If that doesn't work, try specifying a minor version, e.g.:)
apt-get install python3.12-tk
# (Legacy systems where the system Python is a 2.x version)
apt-get install python-tk

# Fedora
dnf install python3-tkinter
# (or use yum instead on RHEL)

# Arch
pacman -S tk
```

### When building from source

First, of course, make sure that you haven't explicitly excluded Tkinter support in the configuration options.

Most commonly, however, the problem occurs because of missing system support. Please install the corresponding *development* package for Tcl/Tk with your system package manager *before* attempting to build.

<section class="notice is-warning">

This is **also** necessary when using Pyenv to set up a new environment, since it generally works by downloading and building from source.
</section>

```
# Debian/Ubuntu (and Mint, Pop! OS etc.)
apt-get install tk-dev
```

<section class="notice is-warning">

**This is separate from any package installed for the system Python**: e.g. `apt-get install python3-tk` will *not* enable Tkinter on Debian for a separate copy of Python built from source but *only* for the system Python. The development package will allow Python to build an additional `_tkinter` module which is a "binding" to the main package.
</section>
</details>

## Windows

When Python is installed on Windows using the official installer, there is an option to include or exclude Tcl/Tk support. Simply "repair" the installation and make sure to check the option to include this.

## MacOS using Brew

Use `brew install python-tk`; if necessary, specify a Python version like `brew install python-tk@3.11`. 

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

## Headless environments

<section class="notice is-warning">

It's **generally not possible to install Tkinter - or any other GUI toolkit** - for [headless server environments like PythonAnywhere](https://help.pythonanywhere.com/pages/TkinterPygameEtc) 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](https://unix.stackexchange.com/questions/276168/what-is-x11-exactly)).
</section>

## Virtual environments

Virtual environments will generally have the same Tkinter support as the Python installation they're based upon. Therefore, start by fixing the "base" installation that the virtual environment is based upon. **However, this won't always work.** If it doesn't, you will probably have to re-create the virtual environment from scratch, after adding Tkinter support to the base.

<section class="notice is-warning">

**It is [not possible to add or remove Tkinter support for an individual virtual environment](https://unix.stackexchange.com/questions/738583).** This is because a virtual environment only differs from its base in terms of the `site-packages`, and *there is no such package for Tkinter* (since, again, it is a standard library component that **cannot be obtained using Pip**).
</section>