Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

IDLE or tkinter will not start: Python is not configured for Tk

ErrorIDLE can't import Tkinter. Your Python may not be configured for Tk.

Short answer

IDLE and tkinter need the _tkinter module, which only exists when Tcl/Tk was available. On Ubuntu's own Python, install python3-tk (and idle for the editor). On a Python you compiled yourself, install the Tcl/Tk development files, such as tk-dev, and run configure and make again.

  • Applies to Python 3.12, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the interpreter you actually run whether tkinter loads. The official test opens a small Tk demo window and shows the Tcl/Tk version.

    which python3
    python3 -m tkinter
  2. 2Match what you see, then jump to its fix

    1. 1which python3 prints /usr/bin/python3 and the import failsThe system Python has no python3-tk packageFix
    2. 2which python3 points into your home folder or /usr/local, and python3-tk made no differenceA Python built from source (or by a version manager) was compiled without Tcl/TkFix

What does the error look like?

  • IDLE can't import Tkinter. Your Python may not be configured for Tk.
  • The necessary bits to build these optional modules were not found

Cause 1 of 2

The system Python has no python3-tk package

1Check

On Ubuntu, tkinter ships separately as python3-tk, and the IDLE editor is its own package that depends on it. Neither is guaranteed on a server or minimal image.

dpkg -l python3-tk idle-python3.12

2Fix

Install the package. Use the idle package that matches your Python minor version if you want the editor.

sudo apt update
sudo apt install python3-tk idle-python3.12

3Verify

The Tk demo window opens.

python3 -m tkinter

Confirmed by packages.ubuntu.com

Did this fix it?

Cause 2 of 2

A Python built from source (or by a version manager) was compiled without Tcl/Tk

1Check

The Tk module is optional. When its development files are missing at build time, the build skips it and lists it near the end of the make output.

python3 -c "import _tkinter"

2Fix

Install the Tcl/Tk development package named in the developer guide, then run configure and make again. Installing it afterwards does nothing to an existing build.

sudo apt install tk-dev
./configure
make -j"$(nproc)"

3Verify

The rebuilt interpreter loads the module.

./python -m tkinter

Confirmed by devguide.python.org

Did this fix it?

How do I stop it coming back?

  • Use the Ubuntu Python for tkinter scripts, and keep source builds for cases that need them.
  • Before compiling Python, install the full -dev package list from the Python developer guide.
  • Read the end of the make output: it names every optional module that was skipped.
  • Run python3 -m tkinter right after installing any new interpreter.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.