ModuleNotFoundError: No module named 'tkinter'

TL;DR: matplotlib defaults to the TkAgg backend, which needs tkinter, and your Python was built without it. Install the tkinter system package for your Python, or switch matplotlib to the Agg backend if you do not need interactive windows.

The error

ModuleNotFoundError: No module named 'tkinter'

Fix it

1. Install tkinter for your OS. On Debian/Ubuntu (match your Python version):

   sudo apt install python3-tk

   On Fedora: sudo dnf install python3-tkinter. On macOS with homebrew python it ships included; with python.org builds, reinstall checking the tkinter option. Expected: package installs.

2. Verify tkinter imports:

   python -c "import tkinter; print('tk ok')"

   Expected: prints tk ok.

3. Retry matplotlib:

   python -c "import matplotlib.pyplot; print('mpl ok')"

   Expected: prints mpl ok.

4. Alternative when no GUI is needed (servers, CI): use the Agg backend before importing pyplot:

   import matplotlib
   matplotlib.use("Agg")
   import matplotlib.pyplot as plt

When this applies

Use this when import matplotlib.pyplot raises the tkinter error, typical on minimal Linux installs, docker images, and some pyenv builds.

When it does not apply

If you need interactive plots on a headless server, Agg alone will not show windows; use a web-based backend or save figures to files. If a different module is missing, that is a separate issue.

Compatibility

All matplotlib versions; the default backend is TkAgg unless configured otherwise.

Root cause

TkAgg renders through Tk, which needs the tkinter bindings compiled into Python. Many system and minimal Python builds skip tkinter, so the backend import fails the moment pyplot loads.

Edge cases

pyenv users must install the tk dev headers and rebuild python to get tkinter. In conda, conda install tk usually fixes it. Setting the MPLBACKEND=Agg environment variable is the zero-code way to force Agg.

GitHub issue freemocap/freemocap#55 reports ModuleNotFoundError: No module named 'tkinter' when importing matplotlib.pyplot, because matplotlib defaulted to the TkAgg backend and the Python install shipped without tkinter. The verified fix: install the tkinter system package for your Python (e.g. the python3-tk OS package) so the Tk backend loads, or set the Agg backend before importing pyplot when no display is needed. Full thread: https://github.com/freemocap/freemocap/issues/55