PlantUML Explained: Turn Plain Text into UML Diagrams
PlantUML lets you describe a diagram in text instead of dragging shapes around a canvas. This guide covers the syntax, common diagram types, and how to render them without uploading anything.
Most diagramming tools start with a blank canvas: drag a box, drag an arrow, nudge it two pixels to the left, repeat. PlantUML skips the canvas entirely. You write a short block of plain text describing the boxes, arrows, and labels, and the engine lays the diagram out for you. The result is a diagram you can store in a repository, diff like code, and regenerate in seconds instead of re-dragging shapes every time a class gets renamed.
This guide walks through what PlantUML syntax looks like, why text-based diagrams hold up better than drawn ones, and how to go from an empty editor to an exported PNG. Every example here works as-is in the PlantUML Editor, a free tool that renders your diagram entirely in your browser - no signup, no upload, just live preview as you type.
What is PlantUML?
PlantUML is an open-source language for describing diagrams as text. You wrap a description between @startuml and @enduml, and the engine parses it and draws the corresponding shapes, arrows, and labels automatically. It covers UML staples - class, sequence, activity, use case, state, and component diagrams - along with extras like entity-relationship diagrams, Gantt charts, and mind maps.
Because the diagram lives as text, it behaves like source code: you can commit it, branch it, review it in a pull request, and see exactly what changed in a diff. Compare that to a .drawio or .vsdx file, where a one-line change is invisible until you open the file and squint at the canvas.
@startuml
actor User
User -> API: POST /login
API -> Database: verify credentials
Database --> API: user record
API --> User: 200 OK + token
@endumlWhy text-based diagrams matter
Diagrams tend to rot. A drag-and-drop chart gets drawn once for a design doc and never touched again, because opening the tool, finding the right file, and re-arranging boxes is friction nobody wants after the deadline passes. Text-based diagrams remove most of that friction.
- Lives next to the code - a
.pumlfile sits in the same repository as the service it documents, so it can be updated in the same pull request. - Reviewable diffs - reviewers see exactly which arrow, actor, or class changed instead of comparing two flattened images.
- No layout babysitting - the engine positions boxes and routes arrows, so you describe relationships instead of pixel coordinates.
- Reusable templates - a sequence diagram for one endpoint can be copied and tweaked for the next in seconds.
How the PlantUML Editor renders diagrams
Traditionally, rendering PlantUML meant installing Java and Graphviz locally, or sending your diagram source to a public rendering server. The PlantUML Editor avoids both: it runs the official PlantUML engine compiled to JavaScript, right in your browser tab. As you type, a short debounce triggers a re-render and the preview pane updates - no server round-trip involved.
Your diagram source never leaves your browser
Architecture diagrams often describe exactly the systems an attacker would want to map, and sequence diagrams can reveal internal service names or auth flows. Because the PlantUML Editor renders locally, that source is never uploaded, logged, or sent to a server - it stays on your device, and it keeps working even offline once the page has loaded.
If your syntax has a mistake - an arrow missing its target, a stray keyword - the editor surfaces a clear error instead of a blank preview, so you can fix the line without losing the rest of your diagram.
Step-by-step: build your first diagram
- Open the PlantUML Editor and either start typing between
@startumland@enduml, or load a starting point from the Examples menu. - Watch the preview pane update as you type - it re-renders on a short debounce, so you get near-instant feedback without waiting for a manual refresh.
- If something looks wrong, check the error message the editor shows for invalid syntax; it points to the line that needs fixing.
- Zoom, fit the diagram to the screen, or switch to fullscreen to check details before you're done.
- Export the result as PNG or SVG, download the raw
.pumlsource, or copy the image straight to your clipboard for a slide or a doc.
For a diagram you want to hand off, generate a shareable link instead of exporting a file - the PlantUML Editor encodes the source directly into the URL, so anyone who opens it renders the same diagram locally in their own browser.
Common diagram types, with examples
PlantUML's syntax changes slightly by diagram type, but the pattern is consistent: describe the participants, then describe how they relate. Here are four you'll reach for constantly.
Sequence diagram: a login request
Sequence diagrams show messages passed between participants over time - ideal for documenting an API call or an auth flow.
Input
@startuml
actor User
User -> API: POST /login
API -> Database: verify credentials
Database --> API: user record
API --> User: 200 OK + token
@endumlOutput
Renders a top-to-bottom sequence diagram with a User actor and API and Database lifelines, solid arrows for the two requests and dashed arrows for the two responses, each labeled with its message.Class diagrams
Class diagrams describe types, their fields and methods, and the relationships between them - inheritance, composition, and association.
@startuml
class Order {
+id: string
+total: number
+addItem(item)
}
class LineItem {
+sku: string
+quantity: number
}
Order "1" *-- "many" LineItem
@endumlActivity diagrams
Activity diagrams map out a process or workflow, including branching logic - useful for documenting a checkout flow or an approval process.
@startuml
start
:Submit order;
if (Payment valid?) then (yes)
:Charge card;
:Send confirmation;
else (no)
:Show error;
endif
stop
@endumlUse case diagrams
Use case diagrams show actors and the goals they accomplish through a system - handy for scoping a feature during planning.
@startuml
left to right direction
actor Customer
actor "Support Agent" as Agent
Customer -- (Browse catalog)
Customer -- (Place order)
Agent -- (Process refund)
@endumlWhere PlantUML fits in your workflow
- Documenting software architecture and API sequence flows alongside the code they describe.
- Sketching UML class and state diagrams during design reviews, before a single line of code is written.
- Embedding diagrams directly in READMEs and wikis, kept up to date because updating them is just editing text.
- Teaching and learning UML, since the preview gives instant visual feedback on syntax changes.
- Producing diagram images for slides and docs without installing Java, Graphviz, or a desktop app.
Common mistakes and how to avoid them
Forgetting @startuml or @enduml
Every diagram needs both tags, and they must match the diagram type you're writing (some diagram families use variants like @startmindmap). Leaving one off is the single most common reason a preview stays blank - check the top and bottom of your source first.
Mixing up arrow syntax between diagram types
A sequence diagram uses -> and --> for calls and returns, a class diagram uses --, *--, and <|-- for association, composition, and inheritance, and an activity diagram often needs no arrows at all. Copying an arrow style from one diagram type into another is a quick way to get an error or an unexpected shape.
Cramming too much into one diagram
A sequence diagram with fifteen participants and forty messages is hard to read no matter how well it's laid out. Split a large flow into smaller diagrams - one per use case or one per subsystem - and link them together in your docs instead.
Unescaped quotes and special characters in labels
Labels containing colons, quotes, or parentheses can be misread as syntax rather than text. Wrap the label in double quotes (as shown with "Support Agent" above) when it contains spaces or punctuation the parser might otherwise interpret literally.
Best practices for maintainable diagrams
- Keep one diagram focused on one concern - a single sequence, a single class hierarchy - rather than trying to capture an entire system at once.
- Store
.pumlfiles next to the code they document so a pull request can update both together. - Start from a template in the PlantUML Editor Examples menu rather than writing every diagram type from scratch.
- Use consistent naming for actors and classes across related diagrams so readers can follow a system end to end.
- Only send share links to people you trust with that diagram's contents, since the source is encoded directly in the URL rather than stored on a server.
Pair PlantUML with your other text tools
If your diagrams reference API payloads, keep the two in sync: format the sample JSON with the JSON Formatter so it is easy to paste into a note alongside the diagram, or run identifiers through Base64 Encode when a sequence diagram needs to show an encoded token in a message label.
Related tools
Pretty-print JSON with configurable indentation and instant validation.
Encode text or files to Base64, with an optional URL-safe variant.
Percent-encode text for safe use in URLs and query strings.
Decode a JWT to inspect its header, payload, and claims instantly.
Related guides
Minified JSON is unreadable and hard to debug. This guide covers how JSON formatting works, when to use it, common mistakes, and how to pretty-print JSON without uploading it anywhere.
Base64 encoding turns arbitrary bytes into safe, portable text. This guide covers how encoding works, UTF-8 pitfalls, URL-safe output, and how to encode text or files without uploading anything.
Spaces, ampersands, and accented letters break URLs unless they are percent-encoded first. This guide covers how URL encoding works, when to use it, and how to avoid the mistakes that cause broken links.
A JWT looks like gibberish, but it is just three Base64URL segments hiding plain JSON. This guide walks through decoding a token, reading its claims, and avoiding the mistakes that cause auth bugs.