matplotlib not showing plot: plt.show() does nothing (tested)

If plt.show() returns and no window appears, check matplotlib.get_backend(). On a machine without a display matplotlib falls back to agg, which cannot open windows, and in matplotlib 3.11.2 it does so without any warning. Tested headless in Docker; fixes: install a GUI toolkit, or savefig.

1. No display: matplotlib falls back to Agg without a word

import matplotlib
import matplotlib.pyplot as plt
print("backend:", matplotlib.get_backend())

plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
print("show() returned; no window appeared")

Output:

backend: agg
show() returned; no window appeared

With MPLBACKEND=TkAgg set, the same script printed the same thing:

backend: agg
show() returned; no window appeared

On a machine with no display (SSH session, Docker, WSL without a GUI, a CI runner, a web server) matplotlib picks the non-interactive agg backend, and in matplotlib 3.11.2 plt.show() then returns immediately with no window and no warning, even with -W always. Print matplotlib.get_backend(): if it says agg, nothing will ever pop up.

2. Even an explicit Agg + show() is silent

import warnings
warnings.simplefilter("always")
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt

plt.plot([1, 2, 3])
plt.show()
print("backend:", matplotlib.get_backend())

Output:

backend: Agg

Many answers online quote "UserWarning: FigureCanvasAgg is non-interactive, and thus cannot be shown". In our tests neither matplotlib 3.11.2 nor 3.8.4 printed it for this script, even with every warning enabled, so do not wait for a warning: the missing window may be the only symptom.

3. Forcing a GUI backend shows the real cause

import matplotlib
try:
    matplotlib.use("TkAgg")
    import matplotlib.pyplot as plt
    plt.figure()
except Exception as e:
    print(type(e).__name__ + ":", e)

Output:

ImportError: Error loading shared library libtk8.6.so: No such file or directory (needed by /usr/local/lib/python3.14/lib-dynload/_tkinter.cpython-314-x86_64-linux-musl.so)

Asking for TkAgg explicitly with matplotlib.use() surfaces the underlying problem, here the Tk library missing from the container. On a desktop the fix is to install the GUI toolkit for your Python (for example Tk for TkAgg); on a headless machine the fix is to save the figure instead.

4. Headless fix: savefig

import os
import matplotlib
matplotlib.use("Agg")                  # explicit: no GUI needed
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])
fig.savefig("/tmp/plot.png", dpi=100)
print(os.path.getsize("/tmp/plot.png") > 0, fig.get_size_inches() * 100)

Output:

True [640. 480.]

Call fig.savefig on the figure object, before plt.close(). The default figure is 6.4 × 4.8 inches, so 640 × 480 pixels at dpi=100.

5. The figure was closed (or never drawn) before show()

import matplotlib.pyplot as plt

fig = plt.figure()
plt.plot([1, 2, 3])
plt.close(fig)                         # closed before show()
print("open figures:", plt.get_fignums())
fig2, ax = plt.subplots()
ax.plot([1, 2])
print("open figures:", plt.get_fignums())

Output:

open figures: []
open figures: [1]

plt.show() only shows figures that are still open. If a helper calls plt.close() (or plt.close("all")) first, get_fignums() is empty and nothing appears. Check it right before show().

6. Checklist

• print(matplotlib.get_backend()): agg means no window is possible.
• Headless: fig.savefig("out.png") and open the file.
• Desktop: install a GUI toolkit and set matplotlib.use("TkAgg") or "QtAgg" before importing pyplot, so a missing toolkit raises an error instead of failing silently.
• Make sure plt.show() is actually reached and plt.get_fignums() is not empty.

Related: matplotlib savefig dpi, size, transparent, blank image · matplotlib errorbar · NumPy RuntimeWarning · operands could not be broadcast together · suppress pandas warnings. Plot shows but the legend is empty? See matplotlib legend not showing.

Seeing MatplotlibDeprecationWarning? See MatplotlibDeprecationWarning: fix, silence or find it.

Written with AI assistance. Measured on 2026-10-23 in Docker (headless): python:3-alpine (Python 3.14.7) with matplotlib 3.11.2 (section 2 also checked on python:3.11-alpine with matplotlib 3.8.4). Each block was run verbatim and the output pasted unedited. Jupyter and VS Code were not tested. PlainTables is our extension; Python and matplotlib are free.