Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Matplotlib refuses to draw text when text.usetex is on

ErrorAn exception is raised when a figure with text.usetex = True is drawn or saved

Short answer

With text.usetex on, Matplotlib shells out to a real LaTeX install. The error means one of the tools it calls is missing from PATH, a needed TeX package such as type1cm is absent, or your own preamble breaks the document. Run each tool from the shell, install what is missing, then turn the preamble off to isolate it.

  • Applies to Matplotlib 3.9 and 3.10, Python 3.12, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the shell for each program Matplotlib needs. Anything that prints nothing is the missing piece.

    which latex dvipng gs
    latex --version | head -n 1
  2. 2Match what you see, then jump to its fix

    1. 1which latex prints nothingNo LaTeX installation on PATHFix
    2. 2LaTeX itself runs, but which dvipng or which gs prints nothingdvipng or Ghostscript is missingFix
    3. 3The LaTeX log inside the Matplotlib error says a .sty file (for example type1cm.sty) was not foundA TeX package is missing from a minimal installFix
    4. 4The error shows a LaTeX error line for your text, and it only appears after you set text.latex.preambleYour own preamble or an unescaped character breaks the documentFix

What does the error look like?

  • An exception is raised when a figure with text.usetex = True is drawn or saved
  • latex, dvipng or gs is not found on PATH

Cause 1 of 4

No LaTeX installation on PATH

1Check

Matplotlib's docs state that usetex needs a working LaTeX installation and that the executables must all be on PATH. Check from the same shell or service account that runs Python.

which latex
echo "$PATH"

2Fix

Install a TeX distribution. Matplotlib's docs mention texlive-full as the easy route because it contains every needed collection. On Windows, add the TeX bin folder to PATH.

sudo apt install texlive-full

3Verify

latex now answers, and the plot renders.

latex --version | head -n 1
python -c "import matplotlib as m; m.use('Agg'); import matplotlib.pyplot as p; m.rcParams['text.usetex']=True; p.title(r'$\alpha$'); p.savefig('t.png')"

Confirmed by matplotlib.org

Did this fix it?

Cause 2 of 4

dvipng or Ghostscript is missing

1Check

For the Agg backends (PNG output) dvipng is required in addition to LaTeX. The PS backend needs PSfrag, dvips and Ghostscript, and the install page asks for Ghostscript 9.0 or newer.

dvipng --version | head -n 1
gs --version

2Fix

Install the missing tools and make sure they are on PATH.

sudo apt install dvipng ghostscript

3Verify

Both commands print a version.

dvipng --version | head -n 1
gs --version

Confirmed by matplotlib.org

Did this fix it?

Cause 3 of 4

A TeX package is missing from a minimal install

1Check

Minimal TeX installs often lack type1cm. The dependency page also lists cm-super and underscore for rendering text with LaTeX.

kpsewhich type1cm.sty cm-super-t1.enc

2Fix

Install the full set of collections (texlive-full does this), or add only the missing packages with your TeX package manager.

sudo apt install texlive-full

3Verify

kpsewhich now prints a path for the file that was missing.

kpsewhich type1cm.sty

Confirmed by matplotlib.org

Did this fix it?

Cause 4 of 4

Your own preamble or an unescaped character breaks the document

1Check

The docs call text.latex.preamble unsupported and ask you to disable it before reporting problems. They also say characters such as # $ % & ~ ^ \ { } need escaping in TeX and that raw strings avoid accidental escapes.

import matplotlib as mpl
print(repr(mpl.rcParams["text.latex.preamble"]))

2Fix

Reset the preamble to its default, use raw strings for labels, and delete the stale Matplotlib tex cache if odd results remain.

import matplotlib as mpl
mpl.rcParams["text.latex.preamble"] = ""
# label = r"$\alpha_1$ 50\% of runs"

3Verify

Re-run the script with the preamble empty. Add your packages back one at a time.

python plot.py

Confirmed by matplotlib.org

Did this fix it?

How do I stop it coming back?

  • In containers and CI, install LaTeX, dvipng and Ghostscript in the image and run one tiny usetex plot at build time.
  • Keep text.usetex off for plots where mathtext (plain $...$ with no LaTeX) is enough.
  • Write labels as raw strings so backslashes are not eaten by Python.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.