Note
Go to the endto download the full example code.
Text rendering with LaTeX#
Matplotlib can use LaTeX to render text. This is activated by settingtext.usetex:True in your rcParams, or by setting theusetex propertyto True on individualText objects. Text handling through LaTeX is slowerthan Matplotlib's very capablemathtext, butis more flexible, since different LaTeX packages (font packages, math packages,etc.) can be used. The results can be striking, especially when you take careto use the same fonts in your figures as in the main document.
Matplotlib's LaTeX support requires a workingLaTeX installation. Forthe *Agg backends,dvipng is additionally required; for the PS backend,PSfrag,dvips andGhostscript are additionally required. For the PDFand SVG backends, if LuaTeX is present, it will be used to speed up somepost-processing steps, but note that it is not used to parse the TeX stringitself (only LaTeX is supported). The executables for these externaldependencies must all be located on yourPATH.
Only a small number of font families (defined by thePSNFSS scheme) aresupported. They are listed here, with the corresponding LaTeX font selectioncommands and LaTeX packages, which are automatically used.
generic family | fonts |
|---|---|
serif ( | Computer Modern Roman, Palatino ( |
sans-serif ( | Computer Modern Serif, Helvetica ( |
cursive ( | Zapf Chancery ( |
monospace ( | Computer Modern Typewriter, Courier ( |
The default font family (which does not require loading any LaTeX package) isComputer Modern. All other families are Adobe fonts. Times and Palatino eachhave their own accompanying math fonts, while the other Adobe serif fonts makeuse of the Computer Modern math fonts.
To enable LaTeX and select a font, use e.g.:
plt.rcParams.update({"text.usetex":True,"font.family":"Helvetica"})
or equivalently, set yourmatplotlibrc to:
text.usetex:truefont.family:Helvetica
It is also possible to instead setfont.family to one of the generic familynames and then configure the corresponding generic family; e.g.:
plt.rcParams.update({"text.usetex":True,"font.family":"sans-serif","font.sans-serif":"Helvetica",})
(this was the required approach until Matplotlib 3.5).
Here is the standard example,Render math equations using TeX:
Note that display math mode ($$e=mc^2$$) is not supported, but adding thecommand\displaystyle, as in the above demo, will produce the same results.
Non-ASCII characters (e.g. the degree sign in the y-label above) are supportedto the extent that they are supported byinputenc.
Note
For consistency with the non-usetex case, Matplotlib special-cases newlines,so that single-newlines yield linebreaks (rather than being interpreted aswhitespace in standard LaTeX).
Matplotlib uses theunderscore package so that underscores (_) areprinted "as-is" in text mode (rather than causing an error as in standardLaTeX). Underscores still introduce subscripts in math mode.
Note
Certain characters require special escaping in TeX, such as:
# $ % & ~ ^ \ { } \( \) \[ \]Therefore, these characters will behave differently depending onrcParams["text.usetex"] (default:False). As noted above, underscores (_) do not requireescaping outside of math mode.
Note
LaTeX always defaults to using a serif font for math (even whenrcParams["font.family"]="sans-serif"). If desired, adding\usepackage{sfmath} torcParams["text.latex.preamble"] lets LaTeXoutput sans-serif math.
PostScript options#
In order to produce encapsulated PostScript (EPS) files that can be embeddedin a new LaTeX document, the default behavior of Matplotlib is to distill theoutput, which removes some PostScript operators used by LaTeX that are illegalin an EPS file. This step produces results which may be unacceptable to someusers, because the text is coarsely rasterized and converted to bitmaps, whichare not scalable like standard PostScript, and the text is not searchable. Oneworkaround is to setrcParams["ps.distiller.res"] (default:6000) to a higher value (perhaps 6000)in your rc settings, which will produce larger files but may look better andscale reasonably. A better workaround, which requiresPoppler orXpdf, canbe activated by changingrcParams["ps.usedistiller"] (default:None) toxpdf. This alternativeproduces PostScript without rasterizing text, so it scales properly, can beedited in Adobe Illustrator, and searched text in pdf documents.
Possible hangups#
On Windows, the
PATHenvironment variable may need to be modifiedto include the directories containing the latex, dvipng and ghostscriptexecutables. SeeEnvironment variables andSetting environment variables in Windows for details.Using MiKTeX with Computer Modern fonts, if you get odd *Agg and PNGresults, go to MiKTeX/Options and update your format files.
On Ubuntu and Gentoo, the base texlive install does not ship withthe type1cm package. You may need to install some of the extrapackages to get all the goodies that come bundled with other LaTeXdistributions.
Troubleshooting#
Try deleting your
.matplotlib/tex.cachedirectory. If you don't knowwhere to find.matplotlib, seematplotlib configuration and cache directory locations.Make sure LaTeX, dvipng and Ghostscript are each working and on your
PATH.Make sure what you are trying to do is possible in a LaTeX document,that your LaTeX syntax is valid and that you are using raw stringsif necessary to avoid unintended escape sequences.
rcParams["text.latex.preamble"](default:'') is not officially supported. Thisoption provides lots of flexibility, and lots of ways to causeproblems. Please disable this option before reporting problems.If you still need help, please seeGet help.