pythontkinterinstallationmodulenotfounderror

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


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:

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


Solution

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

    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.

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

    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:

    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.

    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.

    See also:

    Brew (typically MacOS)

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

    Additional hints: TKinter in a Virtualenv

    Tkinter components

    Some users will find it useful to understand exactly what the Tkinter system contains. There are several components:

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