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

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

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

legend
Shipped orders only
endlegend

skinparam backgroundColor #FDF6E3
skinparam monochrome true
skinparam shadowing false
skinparam dpi 150

Comments start with ' — not //.

Rendering

Tool	How
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

For more

• 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
• Kroki — render PlantUML inside Markdown, AsciiDoc, reStructuredText, …
• PlantUML VS Code extension