IDLE or tkinter will not start: Python is not configured for Tk
IDLE 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.
Fix it fast
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 tkinter2Match what you see, then jump to its fix
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.122Fix
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.123Verify
The Tk demo window opens.
python3 -m tkinterConfirmed by packages.ubuntu.com
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 tkinterConfirmed by devguide.python.org
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix