Matplotlib refuses to draw text when text.usetex is on
An exception is raised when a figure with text.usetex = True is drawn or savedShort 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.
Fix it fast
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 12Match what you see, then jump to its fix
- 1
which latex prints nothingNo LaTeX installation on PATHFix - 2
LaTeX itself runs, but which dvipng or which gs prints nothingdvipng or Ghostscript is missingFix - 3
The 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
The 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
- 1
What does the error look like?
An exception is raised when a figure with text.usetex = True is drawn or savedlatex, 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-full3Verify
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
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 --version2Fix
Install the missing tools and make sure they are on PATH.
sudo apt install dvipng ghostscript3Verify
Both commands print a version.
dvipng --version | head -n 1
gs --versionConfirmed by matplotlib.org
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.enc2Fix
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-full3Verify
kpsewhich now prints a path for the file that was missing.
kpsewhich type1cm.styConfirmed by matplotlib.org
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.pyConfirmed by matplotlib.org
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix