Tools

How to Install Tkinter for PyCharm (Windows, macOS, Linux)

Tools · Published 2026-10-24

You do not install tkinter with pip or through PyCharm's package manager: it is part of Python's standard library and comes with the Python interpreter itself. If import tkinter fails, install or repair a Python build that includes Tcl/Tk, then point your PyCharm project at that interpreter.

Why pip install tkinter fails

Tkinter is a thin Python layer (tkinter plus the C extension _tkinter) over the Tcl/Tk GUI toolkit. Both are compiled into the interpreter when Python is built, so there is no package on PyPI to download. Trying anyway gives:

$ pip install tkinter
ERROR: Could not find a version that satisfies the requirement tkinter (from versions: none)
ERROR: No matching distribution found for tkinter

Searching for "tkinter" in PyCharm's Python Packages tool window ends the same way. Packages on PyPI with similar names (for example tk) are unrelated projects and do not supply the standard-library module, so do not install them as a workaround.

Check whether your interpreter has tkinter

Run these with the exact interpreter your project uses (use python or py on Windows):

python3 -c "import tkinter; print(tkinter.TkVersion)"
python3 -m tkinter

The first prints the Tk version, such as 8.6. The second opens a small demo window that shows the Tcl/Tk version and has a Quit button; if it appears, tkinter works. A Python built without Tk support fails instead. This is real output from a Linux container whose Python was built without Tk:

$ python3 -c "import tkinter; print(tkinter.TkVersion)"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import tkinter; print(tkinter.TkVersion)
    ^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'tkinter'

Other variants of the same problem are ModuleNotFoundError: No module named '_tkinter' (the Python part is present, the compiled extension is not) and ImportError: libtk8.6.so: cannot open shared object file (the extension exists but the Tk library is missing). The fix for all three depends on your operating system.

Installing Tcl/Tk support by operating system

Windows

The installers from python.org include tkinter by default through the optional feature tcl/tk and IDLE. If it was unticked during a custom installation, run the same installer again (or open Settings › Apps › Installed apps, select the Python version and choose Modify), pick Modify, tick tcl/tk and IDLE and finish. The Microsoft Store build of Python also includes tkinter. Embeddable ZIP distributions do not.

Debian and Ubuntu

Distribution Python splits tkinter into its own package:

sudo apt update
sudo apt install python3-tk

If you use an additional Python version from a PPA such as deadsnakes, install the matching package, for example python3.12-tk. The package must match the interpreter version you actually run.

Fedora, RHEL and derivatives

sudo dnf install python3-tkinter

On Arch Linux, install the tk package; the tkinter module itself is already part of the python package.

macOS

• python.org installer: includes its own Tcl/Tk 8.6 build. This is the least troublesome option for GUI work.
• Homebrew: the python@3.x formulae ship without Tk support; it lives in a separate formula matching the Python version, for example brew install python-tk@3.12.
• Apple's /usr/bin/python3 (from the Command Line Tools) has historically shipped with an outdated Tk and may print deprecation warnings or render poorly. Prefer one of the two options above for development.

pyenv

pyenv compiles Python from source, and _tkinter is only built if the Tcl/Tk development headers are present at build time. A Python built without them stays without tkinter until it is rebuilt. Install the headers (tk-dev on Debian/Ubuntu, tk-devel on Fedora, brew install tcl-tk on macOS) and reinstall the version:

pyenv install --force 3.12.7   # use the version you need

On macOS, recent pyenv releases look for Homebrew's tcl-tk automatically; with older ones you may need to pass configure flags. Check the pyenv wiki's build-problems page if the rebuilt interpreter still lacks _tkinter.

conda

Python from Anaconda, Miniconda or conda-forge depends on the tk package and includes tkinter. If it is somehow missing, conda install tk inside the environment restores it.

Make PyCharm use that interpreter

PyCharm runs your code with the project interpreter, which can differ from the python on your terminal's PATH. After fixing tkinter:

1. Open Settings (PyCharm › Settings on macOS) › Project: <name> › Python Interpreter. In the new UI (PyCharm 2023.x and later), you can also click the interpreter name in the status bar at the bottom right.
2. Check the path shown. If it points to a virtual environment, that venv uses the standard library of the base interpreter it was created from. Installing python3-tk for that same base Python is enough; the venv gains tkinter automatically.
3. If the venv was created from a different Python (for instance an old pyenv build without Tk), create a new one: Add Interpreter › Add Local Interpreter › Virtualenv Environment, select the fixed interpreter as the base, then reinstall your packages from requirements.txt.
4. Confirm in PyCharm's Python Console: import tkinter; tkinter.TkVersion.

The JetBrains guide to configuring a Python interpreter documents these dialogs; labels shift slightly between versions.

A minimal test window

Save this as tk_test.py and run it from PyCharm. It uses the themed ttk widgets that the tkinter documentation recommends for new code:

import tkinter as tk
from tkinter import ttk


def main() -> None:
    root = tk.Tk()
    root.title("Tkinter works")
    root.geometry("320x140")

    ttk.Label(root, text=f"Tk {tk.TkVersion} / Tcl {tk.TclVersion}").pack(pady=12)

    counter = tk.IntVar(value=0)
    ttk.Label(root, textvariable=counter).pack()
    ttk.Button(root, text="Click", command=lambda: counter.set(counter.get() + 1)).pack(pady=8)

    root.mainloop()


if __name__ == "__main__":
    main()

A 320×140 window titled "Tkinter works" should appear, showing the Tk and Tcl versions and a counter that increases each time you click the button. Closing the window ends mainloop() and the script exits.

Troubleshooting

• It works in the terminal but not in PyCharm. Different interpreters. Compare import sys; print(sys.executable) in both.
• _tkinter.TclError: no display name and no $DISPLAY environment variable. Tkinter is installed but there is no graphical display: a remote SSH interpreter, Docker, WSL without WSLg, or a CI runner. Run the GUI locally, enable X11 forwarding or WSLg, or use a virtual display such as Xvfb for tests.
• Can't find a usable init.tcl on Windows. The Tcl library files are missing or a stray TCL_LIBRARY/TK_LIBRARY environment variable points elsewhere. Remove those variables or repair the installation.
• Your own file is named tkinter.py. It shadows the standard module and causes confusing attribute errors. Rename it and delete any __pycache__ next to it.
• Old code uses import Tkinter. That is the Python 2 name; in Python 3 the module is lowercase tkinter.

Summary

Tkinter cannot be installed with pip because it is built into Python. Verify it with python -m tkinter. If it is missing, enable "tcl/tk and IDLE" in the Windows installer, install python3-tk (Debian/Ubuntu) or python3-tkinter (Fedora), use the python.org installer or python-tk@3.x on macOS, or rebuild pyenv Pythons with Tk headers. Then select that interpreter, or a virtual environment based on it, under Settings › Project › Python Interpreter in PyCharm.

Read next

More in Tools

Python

PySimpleGUI image buttons

Make image buttons in PySimpleGUI or FreeSimpleGUI with image_filename or base64 image_data, a borderless look, scaling, toggled images and event handling.

Tools

Install packages in PyCharm

Install Python packages in PyCharm via the Packages tool window, interpreter settings or pip; venv vs conda, requirements.txt and fixing import errors.

Tools

Install dlib for PyCharm

Install dlib for a PyCharm project: why pip compiles it, setting up CMake and a C++ compiler, the easier conda-forge route, and fixing Failed building wheel.