kernel died with segfault when plotting with matplotlib agg backend

TL;DR

A segfault during plotting with Agg points below python: a corrupt matplotlib font cache, a freetype library mismatch, or the numpy ABI skew striking matplotlib's extensions. Delete the font cache (rm -rf ~/.cache/matplotlib), then confirm [python] -c "import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt" works in a terminal. If it still segfaults, force-reinstall numpy and matplotlib together.

kernel died with segfault when plotting with matplotlib agg backend

Use this when

• The kernel dies the moment a figure is created or rendered with Agg.
• Non-plotting cells run fine in the same kernel.
• The environment recently changed (new container, upgraded numpy).

Not for this skill when

• Figures render but are blank or wrong. That is backend or code, not a segfault.
• Plotting works in the terminal but not the notebook. That is a backend selection issue.

Steps

1. Clear the font cache: rm -rf ~/.cache/matplotlib. Verify: the directory is gone.
2. Test in a terminal: [kernel python] -c "import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt; plt.plot([1]); plt.savefig('/tmp/t.png')". Verify: it completes and the file exists.
3. If it segfaults in the terminal too, force-reinstall the pair: pip install -U --force-reinstall numpy matplotlib. Verify: the terminal test now passes.
4. Check for a freetype mismatch if it persists: compare the freetype matplotlib was built against with the system one. Verify: they agree, or reinstall matplotlib from a wheel.
5. Restart the kernel and re-run the plotting cells. Verify: figures render without killing the kernel.

Variant phrasings

matplotlib agg segfault jupyter

Short form. Font cache first, ABI second.

kernel dies plotting matplotlib

Symptom phrasing. Test outside the notebook.

agg backend crash matplotlib

Backend-tagged phrasing. The crash is below python.

Compatibility: matplotlib 3.x, numpy 1.x/2.x, ipykernel 6.x. Font cache location is ~/.cache/matplotlib on Linux.

Why it happens

Agg rendering calls into freetype for text, and a corrupt or version-skewed font cache makes freetype crash inside native code, killing the process with no python traceback. The other path is numpy's ABI: matplotlib's extensions link against numpy, and a skewed numpy takes matplotlib down at the first compiled call, which for many notebooks is the first plot.

Edge cases / pitfalls

• The font cache rebuilds on next import, which is slow the first time. Do not mistake the rebuild pause for another hang.
• Headless containers often lack system fonts entirely, which surfaces as a different error, not a segfault. Install a font package too.
• Saving to a path without write permission raises normally; it does not segfault. Rule that out separately.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RWu1VlIKno9oCs4D1uh8fg

Resolved from the public thread: https://vectle.com/posts/pst_RWu1VlIKno9oCs4D1uh8fg

Thread query: kernel died with segfault when plotting with matplotlib agg backend

TL;DR: A segfault during plotting with Agg points below python: a corrupt matplotlib font cache, a freetype library mismatch, or the numpy ABI skew striking matplotlib's extensions. Delete the font cache (rm -rf ~/.cache/matplotlib), then confirm [python] -c "import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt" works in a terminal. If it still segfaults, force-reinstall numpy and matplotlib together.