PlantUML output formats: SVG, PNG, PDF, LaTeX, ASCII compared

PlantUML defaults to SVG, but actual doc workflows — embedded in README, printed to PDF, dropped into LaTeX — have different format requirements. This article compares every output format, best-fit scenarios, and pitfalls.

Output format cheat sheet

1

java -jar plantuml.jar -t<FORMAT> diagram.puml

SVG (default)

1
2

java -jar plantuml.jar -tsvg diagram.puml
# -> diagram.svg

Pros

• Vector, scales without aliasing
• Embedded font + CSS theme
• Text-based, diff-friendly
• Small (kilobytes per diagram)

Cons

• GitHub Markdown requires explicit SVG file embed
• Complex diagrams eat memory
• Editor previews can lag

Embed SVG without pitfalls

1

![login](docs/sequence/login.svg)

1

<img src="diagram.svg" alt="login flow" />

PNG

1

java -jar plantuml.jar -tpng diagram.puml

Pros

• Universal support
• PPT / WeChat embed-friendly
• Static, snapshot-like

Cons

• Fixed resolution (bump DPI for retina)
• Larger than SVG
• No dynamic relayout

DPI

1

java -jar plantuml.jar -tpng -DPI=200 diagram.puml

PDF

1

java -jar plantuml.jar -tpdf diagram.puml

Pros

• Vector print quality
• A4/Letter page sizes adjustable

Embed in LaTeX papers

1

java -jar plantuml.jar -tpdf --latex-bibliography diagram.puml

LaTeX

1
2

java -jar plantuml.jar -tlatex diagram.puml
# -> diagram.tex

Outputs TikZ:

1
2
3
4
5

\begin{tikzpicture}
\node[rectangle, draw] (A) {A};
\node[rectangle, draw, right of=A] (B) {B};
\draw[->] (A) -- (B);
\end{tikzpicture}

Embed in existing LaTeX document

1

java -jar plantuml.jar -tlatex_no_preamble diagram.puml

-tlatex_no_preamble strips \documentclass. \input{diagram.tex} directly.

HTML

1
2

java -jar plantuml.jar -thtml diagram.puml
# -> diagram.html

1
2
3

<div class="plantuml">
<svg>...</svg>
</div>

Good for Flask / Express / Django template embed.

Unicode text / ASCII

1

java -jar plantuml.jar -tutxt diagram.puml

Pure terminal characters. Markdown transcriptions, email, Slack.

Rendered:

1
2
3
4
5
6
7
8

+--------------------+
|     Hello          |
+--------------------+
         |
         v
+--------------------+
|     World          |
+--------------------+

ASCII variants

• -taa ASCII art (basic chars)
• -taa_text ASCII text (more chars)
• -tutxt Unicode (with borders)

README embed modes

Mode A: SVG file reference

1
2
3

docs/sequence/login.puml     <- source
docs/sequence/login.svg     <- rendered
README.md                   <- ![](docs/sequence/login.svg)

Mode B: Mermaid style

1
2
3
4
5

```mermaid
sequenceDiagram
  Alice->>Bob: hello
  Bob-->>Alice: reply
```

1
2
3
4
5
6

### Mode C: plantuml.com URL (no server)

````markdown
![alt](https://www.plantuml.com/plantuml/svg/<encoded>)
````

GitHub renders.

Mode D: self-hosted plantuml server

1

![alt](https://plantuml.puml.online/svg/<encoded>)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

## Format choice by scenario

| Scenario | Format |
|---|---|
| Doc site + GitHub + Notion | SVG (`-tsvg`) |
| PDF paper / print | PDF (`-tpdf`) or LaTeX (`-tlatex`) |
| PPT / WeChat | PNG (`-tpng` DPI=200) |
| Slack / email / IM | Unicode (`-tutxt`) |
| Web templates | HTML (`-thtml`) or SVG |

## Dark mode

Default PlantUML SVG is light. On dark sites it doesn't fit.

### Built-in dark theme

```plantuml
@startuml
!theme dark
class A
A --> B
@enduml

!theme dark but it’s heavy black.

Custom skinparam

1
2
3
4
5
6
7
8
9
10
11

@startuml
skinparam {
  BackgroundColor #161B22
  FontColor #E6EDF3
  BorderColor #30363D
  ArrowColor #58A6FF
}

class A
A --> B
@enduml

Or:

1
2
3
4
5

@startuml
!theme cyborg
class A
A --> B
@enduml

!theme cyborg / !theme black-knight are dark-background presets.

CSS @media auto-switch

1

java -jar plantuml.jar -tsvg -DPLANTUML_DARK_MODE_DETECT=true diagram.puml

-DPLANTUML_DARK_MODE_DETECT=true makes PlantUML emit SVG with CSS media query. Dark mode browser auto-switches.

Performance

Complex class diagrams (>50 nodes):

• SVG: ~200ms
• PNG: ~300ms
• PDF: ~400ms
• LaTeX: ~300ms

CI: render multiple formats

1
2
3
4
5
6
7
8

#!/bin/bash
DIR=docs/architecture

for puml in $(find $DIR -name '*.puml'); do
  java -jar plantuml.jar -tsvg  "$puml"
  java -jar plantuml.jar -tpng -DPI=200 "$puml"
  java -jar plantuml.jar -tpdf  "$puml"
done

Don’t commit all three; the repo holds SVG + source. PNG and PDF go to release artifacts.

Editor embed

1
2
3
4
5
6
7
8
9
10

<style>
  .puml-preview img {
    max-width: 100%;
    height: auto;
  }
</style>

<div class="puml-preview">
  <img src="diagram.svg" alt="sequence diagram" />
</div>

Inline SVG via <object>:

1

<object data="diagram.svg" type="image/svg+xml"></object>

<object> reacts better to light/dark CSS than <img>.

Anti-patterns

1. PNG over SVG in PRs

PNG is large, no diff, slow render. Use SVG.

2. Multiple formats per image

Don’t mix. Pick one canonical. Others as artifacts.

3. No dark mode support

Blog is dark; diagram is light. Mismatch.

4. Font drift

PlantUML default fonts differ across OS — Windows/Linux/macOS each picks a different fallback, breaking layout.

1
2
3
4
5
6

@startuml
skinparam {
  DefaultFontName "Inter"
  DefaultFontSize 12
}
@enduml

Pin fonts in CI too.

Review checklist

• SVG default for web docs?
• Right format per scenario?
• Same font everywhere?
• Dark mode aligned with site theme?

TL;DR

SVG covers 95% of cases. Print wants PDF, IM wants utxt, LaTeX wants TikZ. One source, multiple formats — that’s the canonical doc workflow.