Resolving Matplotlib Backend Errors on macOS When Using pyenv and Tkinter

When learning matplotlib on macOS, the author repeatedly encountered a RuntimeError stating that Python is not installed as a framework, which prevents the default Mac OS X backend from functioning correctly.

The error message also suggested reinstalling Python as a framework or switching backends, and mentioned using pythonw or installing python.app when using Conda.

Because the author manages Python versions with pyenv , the installed interpreter lacks the required framework and the tkinter module, leading to an additional No module named '_tkinter' error.

Two common fixes were tried without success:

Adding the lines import matplotlib matplotlib.use('TkAgg') import matplotlib.pyplot as plt

Appending backend: TkAgg to ~/.matplotlib/matplotlibrc

Both approaches failed because the underlying tkinter library was missing. Attempts to install it with pip3 install tkinter returned “No matching distribution found”.

The article then clarifies that tkinter is the standard Python interface to the Tk GUI toolkit, not bundled with a pyenv‑installed Python on macOS.

As an alternative, the author switched to a different GUI backend. By setting the backend to Qt5Agg:

echo "backend : Qt5Agg" > ~/.matplotlib/matplotlibrc

and installing the required Qt libraries:

brew install pyqt

followed by the Python bindings:

pip install PyQt5

the matplotlib code runs successfully.

The article concludes with a screenshot of the working plot and a link to the original post.