Python "ModuleNotFoundError: No module named '_tkinter'" in CI

Importing tkinter failed because this interpreter has no Tk support. Either the Python build omitted the Tk module, or the Tcl/Tk system libraries it needs aren’t installed on the runner.

What this error means

Code (or a dependency) that imports tkinter raises ModuleNotFoundError: No module named '_tkinter'. It’s common on minimal images and on pyenv-built Pythons compiled without Tk headers present.

Traceback (most recent call last):
  File "gui.py", line 1, in <module>
    import tkinter
ModuleNotFoundError: No module named '_tkinter'

Common causes

System Tcl/Tk package missing

On Debian/Ubuntu the python3-tk package (and Tcl/Tk libs) provides _tkinter. A minimal image lacks it, so the import fails.

Interpreter built without Tk

A Python compiled from source (pyenv) without the Tk dev headers present at build time omits _tkinter entirely; installing Tk afterward isn’t enough - it must be rebuilt.

How to fix it

Install the Tk package

# Debian/Ubuntu (system Python)
apt-get update && apt-get install -y python3-tk
python3 -c "import tkinter; print(tkinter.TkVersion)"

Rebuild a pyenv Python with Tk

For a from-source interpreter, install the Tk dev libs first, then rebuild so _tkinter is compiled in.

apt-get install -y tk-dev tcl-dev
pyenv install 3.12.4   # rebuild with Tk present

Avoid Tk if you don’t need a GUI

If Tk is only pulled in by matplotlib, switch to the Agg backend and the import disappears.

export MPLBACKEND=Agg

How to prevent it

• Install python3-tk (and Tcl/Tk) in images that import tkinter.
• Build pyenv interpreters with Tk dev headers present if you need GUI support.
• Use the Agg backend so headless plotting doesn’t require Tk.

Related guides