PlantUML Cheat Sheet

Overview

PlantUML is an open-source tool that generates UML diagrams from plain text descriptions. It supports sequence, class, activity, component, state, object, deployment, and timing diagrams, plus non-UML diagrams like mind maps, Gantt charts, and JSON/YAML visualization. PlantUML uses a simple, intuitive text syntax that makes diagrams easy to create and version control.

PlantUML requires Java to run and can be used via command line, integrated into IDEs (VS Code, IntelliJ, Eclipse), embedded in documentation tools (Confluence, GitLab), or accessed through the online server at plantuml.com. It outputs PNG, SVG, EPS, and ASCII art formats.

Installation

# Prerequisites: Java Runtime Environment
java -version

# Download PlantUML JAR
wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar

# Generate a diagram
java -jar plantuml.jar diagram.puml

# Generate SVG output
java -jar plantuml.jar -tsvg diagram.puml

# macOS via Homebrew
brew install plantuml

# Linux via package manager
sudo apt install plantuml

# Docker
docker run -v $(pwd):/data plantuml/plantuml diagram.puml

CLI Options

Option	Description
`-tpng`	Output as PNG (default)
`-tsvg`	Output as SVG
`-teps`	Output as EPS
`-ttxt`	Output as ASCII art
`-tpdf`	Output as PDF
`-o <dir>`	Output directory
`-dpi <num>`	Set DPI for raster output
`-charset utf-8`	Set character encoding
`-pipe`	Read from stdin, write to stdout
`-config <file>`	Load configuration file
`-checkonly`	Validate syntax without generating
`-nbthread auto`	Use multiple threads

Sequence Diagrams

@startuml
title Authentication Flow

actor User
participant "Web App" as App
participant "Auth Server" as Auth
database "User DB" as DB

User -> App : Login request
activate App

App -> Auth : POST /oauth/token
activate Auth

Auth -> DB : Validate credentials
DB --> Auth : User record

alt Valid credentials
    Auth --> App : Access token
else Invalid credentials
    Auth --> App : 401 Unauthorized
end

deactivate Auth
deactivate App

note right of Auth : Tokens expire after 1 hour

@enduml

Arrow Types

Syntax	Description
`->`	Solid line with arrow
`-->`	Dotted line with arrow
`->>`	Thin arrow
`-->>`	Thin dotted arrow
`->x`	Lost message
`<->`	Bidirectional

Class Diagrams

@startuml
abstract class Shape {
    # color: String
    + {abstract} area(): double
    + {abstract} perimeter(): double
}

class Circle {
    - radius: double
    + area(): double
}

class Rectangle {
    - width: double
    - height: double
    + area(): double
}

interface Drawable {
    + draw(canvas: Canvas): void
}

Shape <|-- Circle
Shape <|-- Rectangle
Drawable <|.. Circle
Drawable <|.. Rectangle

@enduml

Visibility Markers

Marker	Visibility
`+`	Public
`-`	Private
`#`	Protected
`~`	Package-private
`{static}`	Static member
`{abstract}`	Abstract member

Activity Diagrams

@startuml
start
:Receive order;

if (Payment valid?) then (yes)
    :Process payment;
    fork
        :Pack items;
    fork again
        :Send confirmation email;
    end fork
    :Ship order;
else (no)
    :Notify customer;
    stop
endif

:Deliver to customer;
stop
@enduml

Component Diagrams

@startuml
package "Frontend" {
    [React App] as react
    [State Manager] as state
}

package "Backend" {
    [API Gateway] as gateway
    [Auth Service] as auth
    [User Service] as users
}

database "PostgreSQL" as pg
database "Redis" as redis

react --> gateway : HTTPS
gateway --> auth
gateway --> users
users --> pg
auth --> redis
@enduml

State Diagrams

@startuml
[*] --> Draft

Draft --> Review : Submit
Review --> Approved : Approve
Review --> Draft : Request changes
Approved --> Published : Publish
Published --> Archived : Archive

state Review {
    [*] --> PeerReview
    PeerReview --> TechReview
    TechReview --> [*]
}
@enduml

Configuration and Theming

@startuml
skinparam backgroundColor #FEFEFE

skinparam class {
    BackgroundColor #E8F5E9
    BorderColor #2E7D32
    ArrowColor #1B5E20
    FontSize 14
}

skinparam sequence {
    ArrowColor #1565C0
    ParticipantBackgroundColor #E3F2FD
}
@enduml

Themes

@startuml
!theme cerulean
' Available: amiga, aws-orange, cerulean, cyborg,
' mars, materia, metal, minty, plain, sketchy-outline
@enduml

Advanced Usage

Mind Maps

@startmindmap
* Project
** Planning
*** Requirements
*** Timeline
** Development
*** Frontend
*** Backend
** Testing
*** Unit Tests
*** Integration
@endmindmap

JSON Visualization

@startjson
{
  "name": "API Config",
  "version": "2.0",
  "endpoints": [
    { "path": "/users", "method": "GET" },
    { "path": "/orders", "method": "POST" }
  ]
}
@endjson

Include Files and Preprocessor

@startuml
!include common-styles.puml
!define PRIMARY_COLOR #1a73e8

!procedure $service($name, $desc)
    rectangle "$name\n<size:10>$desc</size>" as $name
!endprocedure

$service("API", "REST Gateway")
$service("DB", "PostgreSQL")
API --> DB
@enduml

Troubleshooting

Issue	Solution
Java not found	Install JDK 8+ and ensure java is in PATH
Graphviz required	Install Graphviz: `apt install graphviz`
Diagram too large	Add `scale 0.7` or split into multiple diagrams
Encoding issues	Use `-charset utf-8` flag
VS Code preview not working	Install PlantUML extension; configure jar path
Slow rendering	Use `-nbthread auto` for parallel processing
Font missing in output	Install the font or use skinparam fontName
SVG text not selectable	Ensure `-tsvg` is used