Cheatsheets:PlantUML

Quick reference for smart people — part of our dev cheatsheets collection.

PlantUML is a text-based diagramming language: describe a diagram in a few lines of plain text, render it to PNG, SVG, or ASCII art. The source is just text, so diagrams live in version control and diff cleanly. One syntax covers sequence, class, use case, activity, state, component and deployment diagrams.

New to PlantUML? The Quick Start Guide may interest you.

Basic example

Wrap every diagram in @startuml ... @enduml, save as .puml and render — see Rendering:

Source (.puml)	Rendered
@startuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response Alice -> Bob: Another request Alice <-- Bob: Another response @enduml

Sequence diagrams

The workhorse. A message is sender arrow receiver: text — the text after the colon is the label.

Arrow	Renders as
->	solid line, no arrowhead
-->	dashed line, no arrowhead (typical reply)
->>	solid line with arrowhead
-->>	dashed line with arrowhead
-x	line ending in a cross (destroys the lifeline)
-)	line ending in an open arrowhead

Solid for synchronous calls, dashed for replies and asynchronous messages.

Participants — declare to control order and role. as NAME gives an alias: the quoted text is displayed, the alias is used in messages.

@startuml
participant "Web App" as WA
actor "Customer" as C
database "Postgres" as DB
entity E
control Ctrl
boundary B
queue Q
@enduml

Role keywords: actor, participant, database, entity, control, boundary, queue.

Activations, notes and fragments:

Source (.puml)	Rendered
@startuml participant "Web App" as WA database "Postgres" as DB WA -> DB: SELECT * FROM orders activate DB DB --> WA: rows deactivate DB note right of DB: covered by index alt rows found WA -> WA: render table else empty WA -> WA: show placeholder end loop retry x3 WA -> WA: backoff end @enduml

activate / deactivate — draw a lifeline bar. Shorthand: DB ++ ... DB --; return value sends a dashed reply and deactivates.

Fragments — alt/else, opt, loop, par/and, break, critical, group label — all close with end.

Notes — note left of X, note right of X, note over X, note over X, Y.

Numbering — autonumber labels messages 1, 2, 3...

Class diagrams

Source (.puml)	Rendered
@startuml class Animal { +name: string -age: int +speak(): void } Animal <|-- Dog Dog *-- Collar @enduml

Visibility markers: + public, - private, # protected, ~ package. Kinds: abstract class, interface, enum.

Relations — labels and multiplicities go at the ends:

Symbol	Meaning
Animal <|-- Dog	inheritance (also class Dog extends Animal)
..|>	realization (implements an interface)
*--	composition
o--	aggregation
-- / -->	association
..>	dependency

Dog "1" *-- "0..*" Collar : has

Use case diagrams

Source (.puml)	Rendered
@startuml left to right direction actor Customer rectangle "Web shop" { (Login) (Browse catalog) } Customer --> (Login) (Login) ..> (Browse catalog) : include @enduml

Use cases in parentheses (Login) or usecase "Login" as L; boundaries with rectangle "name" { ... } or package. Dotted arrows express include / extend.

Activity diagrams

Source (.puml)	Rendered
@startuml start :Fetch order; if (in stock?) then (yes) :Ship order; else (no) :Notify customer; endif stop @enduml

:action; is a step; if (cond) then (yes) ... else (no) ... endif a decision. Also while (cond) ... endwhile and fork ... end fork for concurrency.

State diagrams

Source (.puml)	Rendered
@startuml [*] --> Idle Idle --> Running : start() Running --> Idle : stop() Running --> [*] : terminate @enduml

[*] is the initial/final state; State --> State : event labels a transition. Long names: state "Waiting for input" as Waiting.

Component & deployment

Source (.puml)	Rendered
@startuml node "Server" { [Web] --> [App] } node "Database" { database "Postgres" as pg } [App] --> pg @enduml

Square brackets for components, database "name" for datastores, node "name" { ... } / package { ... } for containers.

Common syntax

Comments and document-level decorations — title, header, footer, legend:

' single-line comment
/' multi-line
   comment '/

title Order flow
' diagram title
header v1.0
' repeated header
footer page %page% of %lastpage%
' %page%/%lastpage%: page numbers

Start Comments ' at the beginning of a new line. Avoid trailing comments: title Order flow ' diagram title can cause a parse error as plantUML considers non-leading ' orphaned.

In a header/footer, %page% / %lastpage% become page numbers once the diagram spans several pages.

Source (.puml)	Rendered
@startuml title Order flow header v1.0 footer confidential Alice -> Bob: Request Bob --> Alice: Response @enduml
@startuml legend right Shipped orders only endlegend Alice -> Bob: Ship order Bob --> Alice: OK @enduml

Creole

Creole is a lightweight markup for styling text anywhere in a diagram — labels, notes, titles, class members. All diagram types support it.

Source (.puml)	Rendered
@startuml Alice -> Bob: hello --there-- here ... Some ~~long delay~~ ... Bob --> Alice: ok note left This is **bold** This is //italics// This is ""monospaced"" This is --stricken-out-- This is __underlined__ This is ~~wave-underlined~~ end note @enduml

Creole	Renders as	HTML equivalent
**bold**	bold	<b>…</b>
//italics//	italic	<i>…</i>
""monospaced""	monospaced	<font:monospaced>…</font>
--stricken-out--	strikethrough	<s>…</s>
__underlined__	underlined	<u>…</u>
~~wave-underlined~~	wavy underline	<w>…</w>

In double-quoted strings — ""monospaced"" works in quoted content — titles, notes, message labels — but not in quoted element names like participant "Alice ..." or state "Waiting ..." as W: the "" collides with the string delimiter and the diagram fails to parse. Use the HTML form there instead:

Source (.puml)	Rendered
@startuml title "The ""answer"" is 42" participant "Alice <font:monospaced>the Great</font>" as Alice Alice -> Bob: ""mono"" label @enduml

Source (.puml)	Rendered
@startuml object demo { * Bullet list * Second item ** Sub item } note as n * Bullet list * Second item ** Sub item ---- # Numbered list # Second item ## Sub item end note @enduml

Lists — * bullet, # numbered; repeat the marker to nest (**, ##). You cannot mix bullets and numbers in one list.

Horizontal lines — ---- single, ==== double, ____ strong, ..My title.. dotted with title, ==Title== / --Another title-- with a title.

Source (.puml)	Rendered
@startuml title "The ""answer"" is <U+221E>" Alice -> Bob: <:1f600:> [[http://plantuml.com docs]] Alice -> Bob: Recolor: <#green:sunny:> note right = Heading == Sub heading <code> main() { printf("Hello world"); } </code> end note @enduml

Links — [[http://plantuml.com]], [[http://plantuml.com This label is printed]], with tooltip [[http://plantuml.com{Optional tooltip} This label is printed]] — three brackets link to a field or method on class diagrams.

Emoji & icons — Twemoji emoji are always available (no font dependency) and already colored: <:1f600:>, recolored <#green:sunny:>. OpenIconic icons: <&heart>. List them with the special commands emoji and listopeniconic.

Headings & special chars — inside quoted multi-line labels: = Head, == Sub, === Sub-sub. Any Unicode char works directly, or as <U+221E> (hex) / ∞ (decimal).

Code — <code>…</code> shows source code without syntax highlighting.

Legacy HTML — colors, sizes, images, sub/superscripts: <color:red>…</color>, <back:cadetblue>…</back>, <size:18>…</size>, <img:https://…>, <sub> / <sup>.

Source (.puml)	Rendered
@startuml Alice -> Bob: <b>Hello World</b> Alice -> Bob: ~<b>Hello World~</b> @enduml
@startuml Alice -> Bob: [[Wiki Home]] Alice -> Bob: ~[[Wiki Home]] @enduml

Escaping — ~ prints the next special character literally; unescaped, PlantUML interprets it as creole markup:

Full reference: PlantUML Creole.

Notes

A note is a box of text attached to an element of any diagram type — participant, class, state, use case, link. Sequence-diagram notes are covered in Sequence diagrams; here is the general shape:

Source (.puml)	Rendered
@startuml class Animal note left of Animal : speaks note right of Animal : eats note top of Animal : alive note bottom of Animal : breathes @enduml
@startuml participant Alice participant Bob Alice -> Bob: hi note over Alice : single line note over Alice, Bob : over a range @enduml
@startuml start :Fetch order; note : floating single-line note :Ship order; stop @enduml

Placement — left of X, right of X, top of X, bottom of X, works in the single-line format with the text after a colon, but may not work with other note syntaxes in some scenarios.

In sequence diagrams over X / over X, Y span one or a range of participants; in activity diagrams note alone (or note right) floats beside the current step.

Long text, or several lines: open a note block and close with end note. A note with a quoted title becomes free-floating — attach it to an element with a dotted line:

Source (.puml)	Rendered
@startuml start :Fetch order; note right may block for seconds end note :Ship order; stop @enduml
@startuml class Animal note "why it matters" as N1 Animal .. N1 @enduml
@startuml participant Alice participant Bob Alice -> Bob: hi note over Alice line one line two end note note over Alice, Bob over a range end note @enduml
@startuml start :Fetch order; note floating multi-line note end note :Ship order; stop @enduml

Theme

Swap the whole look with one directive at the top of the diagram — themes ship with PlantUML, nothing to install:

Source (.puml)	Rendered
@startuml !theme spacelab class Example { Theme spacelab } @enduml

• help themes renders the full list of built-in themes.
• Your own theme: !theme foo from /path/to/folder — a file named puml-theme-foo.puml (remote URLs work too).
• Some themes add message helpers: $success("…"), $failure("…"), $warning("…").

Browse the gallery of official themes. Full reference: PlantUML Themes.

Style

CSS-like <style> blocks replace the deprecated skinparam. Selectors target everything (element), one diagram type (sequenceDiagram, classDiagram, …) or one element (participant, arrow, node, …):

Source (.puml)	Rendered
@startuml <style> element { BackGroundColor: #AAA; } sequenceDiagram { participant { FontColor: green; FontSize: 26; FontStyle: italic; LineColor: #E00; } arrow { FontColor: red; LineColor: blue; } } </style> participant Alice participant Bob Alice -> Bob : hello @enduml

Common properties: FontColor, FontSize, FontStyle, FontName; BackGroundColor, LineColor, LineThickness, RoundCorner, Padding, Shadowing. Custom classes: tag an element as X <<primary>>, then style .primary { ... }.

Full reference: PlantUML Styles.

Rendering

Tool	How
This wiki	<uml> ... </uml> — see rendering diagrams on this wiki
CLI	java -jar plantuml.jar diagram.puml → diagram.png (Java required; GraphViz only for some diagram types)
VS Code	PlantUML extension — Alt+D previews the diagram live
Browser	plantuml.com online server; Kroki
GitLab	```plantuml fenced blocks render natively (when enabled on the instance)

CLI options:

plantuml diagram.puml            # PNG (default)
plantuml -tsvg diagram.puml      # SVG
plantuml -tutxt diagram.puml     # ASCII art
plantuml -o out/ diagram.puml    # output directory
plantuml *.puml                  # whole directory

• PlantUML — official site; every diagram type has its own page (sequence-diagram, class-diagram, use-case-diagram, …)
• Quick Start Guide — install, first diagram
• PlantUML Language Reference Guide — the full syntax
• PlantUML Creole — styled text in any diagram
• PlantUML Themes — built-in themes, one-line look change
• PlantUML Styles — CSS-like styling, the skinparam replacement
• Kroki — render PlantUML inside Markdown, AsciiDoc, reStructuredText, …
• PlantUML VS Code extension