plantuml 
Embed PlantUML diagrams in LaTeX documents
Write PlantUML diagrams directly in your LaTeX document:
\begin{plantuml}
Alice -> Bob: Hello
\end{plantuml}
The package renders the diagram with a local plantuml.jar or a PlantUML server and includes it as TikZ, PDF, PNG, SVG, or EPS.
It works with lualatex and pdflatex.
Rendered diagrams are cached, and can be committed for builds without shell escape, e.g., on Overleaf.
Preconditions
- Environment variable
PLANTUML_JARset to the location ofplantuml.jar. You get it from https://sourceforge.net/projects/plantuml/files/plantuml.jar/download. Not needed when renderingeps/png/svgthrough a PlantUML server (see Rendering via a PlantUML server). If neither a jar nor a server is available, the diagram is replaced by a visible placeholder rather than aborting the build. - Windows: Environment variable
GRAPHVIZ_DOTset to the location ofdot.exe. Example:C:\Program Files (x86)\Graphviz2.38\bin\dot.exe. You can install graphviz usingchoco install graphviz. - lualatex or pdflatex available, called with the command line parameter
-shell-escape. - For
output=pdf, use a PlantUML jar that can write PDF: the defaultplantuml-<version>.jar(GPL) orplantuml-epl-<version>.jarfrom the PlantUML releases. The permissively licensed jars (plantuml-mit-*,plantuml-asl-*,plantuml-bsd-*,plantuml-lgpl-*,plantuml-gplv2-*) lack the PDF library and fail withNoClassDefFoundError: org/openpdf/....output=pdfneeds neither inkscape nor a LaTeX engine for PlantUML, and the text in the diagram stays searchable. The PDF uses one of the standard PDF fonts Times-Roman, Helvetica, or Courier, not embedded, regardless ofskinparam defaultFontName: names containingMonoorCouriergive Courier, names containingSerifgive Times-Roman (including PlantUML’s defaultSansSerif), all others give Helvetica. For a sans-serif diagram, useskinparam defaultFontName Helvetica. If the font must be embedded (e.g., PDF/A or print), useoutput=svg,output=eps, oroutput=latex. - In case you want to have SVG images converted to PDF, ensure that
inkscape.exeandpdfcropare in your path. You can get inkscape usingchoco install inkscape.pdfcropshould be part of your latex distribution.
Examples
Minimal Example
LaTeX source:
\documentclass{scrartcl}
\usepackage{plantuml}
\begin{document}
\begin{plantuml}
!theme cerulean-outline
Alice -> Bob: test
\end{plantuml}
\end{document}
The !theme line is optional; it picks a PlantUML colour theme (the examples use
cerulean-outline for a cleaner
look than the colourful default). @startuml and @enduml are optional: when the diagram body omits them,
PlantUML adds them automatically (issue #4),
so the examples here leave them out. You may still write them explicitly if you
prefer.
Compilation: lualatex -shell-escape example-minimal (or pdflatex -shell-escape example-minimal)
Result:
Rendering from a File
Use \plantumlinput{<file>} to render a diagram stored in an external PlantUML
source file, analogous to minted’s
\inputminted and listings’ \lstinputlisting
(issue #3):
\documentclass{scrartcl}
\usepackage{plantuml}
\begin{document}
\plantumlinput{example-input-file.puml}
\end{document}
It honors the output mode and reuses the same caching, server, and
-output-directory handling as the plantuml environment. The file is read
relative to the current working directory, so paths in subdirectories (e.g.
\plantumlinput{diagrams/foo.puml}) work when compiling from the project root.
See example-input-file.tex.
Example Class Relations Rendered Using SVG
LaTeX source:
\documentclass{scrartcl}
\usepackage{graphics}
\usepackage{epstopdf}
\epstopdfDeclareGraphicsRule{.svg}{pdf}{.pdf}{
inkscape "#1" --export-text-to-path --export-filename="\OutputFile"
}
\usepackage[output=svg]{plantuml}
\begin{document}
\begin{plantuml}
!theme cerulean-outline
class Car
Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns
\end{plantuml}
\end{document}
For older Inkscape use this LaTeX source:
\documentclass{scrartcl}
\usepackage{graphics}
\usepackage{epstopdf}
\epstopdfDeclareGraphicsRule{.svg}{pdf}{.pdf}{
inkscape -z --file=#1 --export-pdf=\OutputFile
}
\usepackage[output=svg]{plantuml}
\begin{document}
\begin{plantuml}
!theme cerulean-outline
class Car
Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns
\end{plantuml}
\end{document}
Compilation: lualatex -shell-escape example-class-relations (or pdflatex -shell-escape example-class-relations)
Result:
Rendering via a PlantUML server
Instead of a local plantuml.jar, eps, png, and svg diagrams can be rendered by a
PlantUML server over HTTP. This
needs only curl — no Java and no local PlantUML installation — which is handy
on CI and shared build machines (see issue #6).
Point the package at a server with the server option:
\usepackage[output=svg, server=https://www.plantuml.com/plantuml]{plantuml}
Alternatively set the PLANTUML_SERVER environment variable (the package option
takes precedence over it):
export PLANTUML_SERVER=https://www.plantuml.com/plantuml
You can run your own server, for example with Docker:
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
# then use server=http://localhost:8080
Notes:
- For vector output without extra tools, use
output=eps: LaTeX converts the EPS to PDF itself (viaepstopdf/Ghostscript, shipped with TeX Live), so neither inkscape nor a local jar is needed. Its text is drawn as outlines, so it is sharp but not searchable in the PDF; usesvg(needs inkscape) for real text. The server offers nopdforlatex/TikZ output. - When a server is configured,
output=eps,output=png, andoutput=svgare rendered by it.output=pdfandoutput=latex(TikZ, the default) always use the localplantuml.jar, as the server cannot produce them, so keepPLANTUML_JARset for those. - See
example-server--eps.tex,example-server--png.tex, andexample-server--svg.texfor complete examples. - The diagram source is sent hex-encoded in the request URL, so a very large diagram may hit the server’s URL-length limit.
Caching
Generated diagrams are cached by a hash of their source, similar to
minted and
memoize. Each diagram is written to
plantuml-<hash>-converted-to.<ext>, and PlantUML (or the server) is invoked
only when no file for that hash exists yet. Unchanged diagrams — as well as
repeated or reordered ones — reuse the cached output, so recompiles are fast and
only edited diagrams are regenerated. The -converted-to suffix means the
standard TeX .gitignore
already ignores these files (via *-converted-to.*), so no extra entry is
needed. Delete the plantuml-*-converted-to.* files to clear the cache.
Committing rendered diagrams (e.g. for Overleaf)
The cached files can be committed, so the document builds where PlantUML is not
available, for instance on Overleaf or without -shell-escape. A diagram whose
plantuml-<hash>-converted-to.* file exists is used as is; neither Java nor
shell escape is needed for it. Only new or changed diagrams need PlantUML: build
locally with PLANTUML_JAR set and -shell-escape, then commit the new files.
Until then, such a diagram shows the “could not be generated” placeholder.
This also works with -output-directory: a diagram file is looked up in the
output directory first, then next to the document.
TeX Live before 2023 does not pass the output directory to packages: lualatex
reads it from its command line, pdflatex via ps (Linux and macOS only).
The standard TeX .gitignore ignores these files, so add an exception:
!plantuml-*-converted-to.*
Files of outdated diagrams are not removed automatically. To clean up, delete all
plantuml-*-converted-to.* files, build once, and commit the result.
Global Preamble
The default PlantUML style is colorful, which is not ideal for printouts. Instead
of repeating skinparam settings in every diagram, set a global preamble once
that is applied to all diagrams (issue #5).
Write it inline with the plantumlpreamble environment:
\begin{plantumlpreamble}
skinparam monochrome true
skinparam backgroundColor white
skinparam defaultFontName sans-serif
\end{plantumlpreamble}
…or keep it in a file and point at it with \plantumlpreamblefile{<file>}. Either
form affects every diagram that follows (set it once near the top of the
document). The preamble is folded into the diagram cache key, so changing it
regenerates the diagrams. See example-preamble.tex.
The local jar applies the preamble to every diagram via PlantUML’s -config. The
PlantUML server has no such option, so there the preamble is prepended to the
source instead; this styles the usual marker-less diagrams, but a server diagram
that spells out its own @startuml/@enduml keeps the default style (render it
through the local jar if you need the preamble applied).
Captions and Labels
Diagrams can carry a numbered, \ref-able caption (issue #8).
The options are:
caption={...}— the caption text,label={...}— a\labelfor cross-references,float— place the diagram in a floatingfigure(optional placement, e.g.float=htbp;float=Hneeds thefloatpackage). Withoutfloatthe diagram and its caption are typeset in place (no floating), like listings’caption=— which avoids the erratic placement of a barefigure.
\plantumlinput takes these as an optional argument:
\plantumlinput[caption={A diagram from a file.}, label={fig:demo}]{diagram.puml}
The plantuml environment can’t take an optional argument (a verbatim
environment without a mandatory argument can’t carry one), so set the options for
the next environment with \plantumlset, in the spirit of \lstset:
\plantumlset{caption={A sequence diagram.}, label={fig:seq}}
\begin{plantuml}
Alice -> Bob: hi
\end{plantuml}
See example-caption.tex.
Diagram Font (latex/TikZ output)
With the default output=latex (TikZ), PlantUML computes each box’s size using a
sans-serif font, then emits TikZ that your document typesets. If that text is
set in the document’s default (serif) font, it doesn’t fit the boxes and the
margins look uneven (issue #14).
The package therefore renders the diagram text with \PlantUmlTikzFont, which
defaults to \sffamily so the text matches the boxes. Change it if needed:
\renewcommand\PlantUmlTikzFont{\rmfamily} % serif, e.g. to match a serif skinparam
\renewcommand\PlantUmlTikzFont{} % use the surrounding document font
png/svg output is unaffected (PlantUML renders the text itself), so it is the
simplest choice when exact text fit matters. See example-mindmap.tex.
Beamer
The package works in beamer (issue #11).
The only requirement is that any frame containing a plantuml environment is
declared [fragile], because the environment captures its body verbatim:
\documentclass{beamer}
\usetheme{moloch}
\usepackage{plantuml}
\begin{document}
\begin{frame}[fragile]{PlantUML in Beamer}
\begin{plantuml}
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
\end{plantuml}
\end{frame}
\end{document}
Without [fragile] you get errors such as Paragraph ended before
\beamer@doframe was complete. See example-beamer.tex.
Installation
Your latex distribution should take care.
For manual installation, copy plantuml.* to your local texmf folder in the sub directory tex/latex/plantuml.
See the discussion at tex.sx for the concrete location of the folder on your system.
Development
ADR-0001 explains why pdfLaTeX calls PlantUML via shell escape (#1).
The release is built using GitHub Actions (workflow file) using release.sh.
Release preparation:
- Adapt copyright year (line 1)
- Adapt as date and version number (line 6) in
plantuml.sty. - Adapt
CHANGELOG.md. - Set a git tag and push.
- Upload
plantuml.tar.gz(artifactctanof the Release workflow run for the tag) to CTAN.
Alternative Solutions
TikZ-UML is a very powerful package based on TikZ. More alternative solutions are collected at the CTAN topic UML.
License
SPDX-License-Identifier: LPPL-1.3c+