Learn AI Create the Future — with Pranay
Main site

Error database

UserWarning: Matplotlib is currently using agg, which is a non-GUI backend

plt.show() has no window to draw into — matplotlib fell back to its file-only backend. Save the figure on servers, or install a GUI backend on desktops and WSL.

The message you saw
UserWarning: Matplotlib is currently using agg, which is a non-GUI backend

By Updated

The error

Output
UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
  plt.show()

Newer matplotlib words it:

Output
UserWarning: FigureCanvasAgg is non-interactive, and thus cannot be shown

What it means

Matplotlib draws through a backend — the layer connecting figures to an output medium. GUI backends (QtAgg, TkAgg, MacOSX) open windows; agg renders only into memory and files. Matplotlib picked agg because it found no usable GUI toolkit or no display. plt.show() then has nowhere to show, and warns instead of failing. Your plotting code is fine; the environment has no window system attached.

Why it happens

Headless environments — SSH sessions, servers, Docker, WSL without WSLg — genuinely have no display, and agg is correct there. On desktops, the common cause is that no GUI toolkit is installed in the environment: matplotlib needs tkinter or a Qt binding to open windows, and minimal Python installs lack both.

How to fix it

1. On servers and headless machines: save the figure — the right answer, not a consolation.

python
import matplotlib
matplotlib.use("Agg")                 # explicit: file output intended
import matplotlib.pyplot as plt

plt.plot(losses)
plt.xlabel("epoch")
plt.savefig("loss_curve.png", dpi=150, bbox_inches="tight")
plt.close()

Then copy the file over, or view it in your editor's file browser.

2. In Jupyter, plots render inline — no GUI backend needed. Modern Jupyter does this automatically; if figures stopped appearing, reset the backend:

python
%matplotlib inline

3. On a desktop that should show windows, install a GUI toolkit.

bash
pip install PyQt6

Or system tkinter on Linux: sudo apt install python3-tk. Restart Python; matplotlib auto-detects the new backend. Force it if needed:

python
import matplotlib
matplotlib.use("QtAgg")

4. In WSL2 on Windows 11, update WSL and it works. WSLg provides a display for Linux GUI apps:

powershell
wsl --update

Then install a toolkit as in fix 3 inside WSL. On Windows 10 (no WSLg), save files instead — or run an X server, which is more ceremony than it is worth for plots.

5. Check what backend is active when confused.

python
import matplotlib; print(matplotlib.get_backend())

How to prevent it

Decide the output mode per context and write it down in the script: interactive windows for local exploration, savefig for anything that runs on servers, inline for notebooks. Training scripts should always save figures — a run you launch over SSH tonight should not depend on a display existing.