PlantUML ASCII Diagram Generator

👤 Github

•

📅 January 27, 2026

•

⭐ 19.5K

Introduction

The PlantUML ASCII Diagram Generator is a specialized utility designed to bridge the gap between complex system modeling and text-based environments. It allows developers to generate structured visual representations—such as sequence diagrams, class hierarchies, and flowcharts—directly within terminal windows, README files, or version control comments where graphical rendering isn’t supported.

By leveraging the power of PlantUML text mode, this tool ensures your documentation remains lightweight and version-control friendly while providing clear visual context.

Key Features:

Broad Diagram Support: Generate Sequence, Class, Activity, State, Component, Use Case, and Deployment diagrams.
Unicode Enhancement: Use the utxt format to leverage box-drawing characters for a more polished, professional look.
Terminal-Ready: Perfect for SSH sessions, CLI-based workflows, and environments lacking graphical displays.
Seamless Integration: Works via standard CLI commands or directly through Java JAR execution.

Installation

Depending on your operating system, use the following commands to install the core PlantUML engine:

macOS

brew install plantuml

Linux

# Ubuntu/Debian
sudo apt-get install plantuml

# RHEL/CentOS
sudo yum install plantuml

Manual JAR Download If you prefer not to use a package manager, download the JAR directly:

wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar

Usage

To generate a diagram, first create a .puml file with your PlantUML syntax.

1. Create a Source File

@startuml
participant Bob
actor Alice

Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml

2. Run the Generator

You can choose between standard ASCII or Unicode-enhanced output:

Standard ASCII: plantuml -txt diagram.puml
Unicode ASCII (Recommended): plantuml -utxt diagram.puml

3. Output Formats

Flag	Format	Description
`-txt`	ASCII	Uses pure ASCII characters for maximum compatibility.
`-utxt`	Unicode	Uses box-drawing characters for better visual quality.

Pro Tip: Use the -utxt flag whenever your environment supports UTF-8. The box-drawing characters make relationships and boundaries much easier to distinguish at a glance.

Supported Diagram Examples

Sequence Diagrams

Sequence diagrams are the most common use case for ASCII art, providing a clear timeline of interactions.

# Example Command
plantuml -utxt sequence.puml

Class & Activity Diagrams

You can model object-oriented structures or logic flows without ever leaving your text editor. The generator handles the layout automatically, ensuring that even complex logic like if/then/else blocks are rendered clearly.

Advanced Options

Manage your workflow efficiently with these command-line arguments:

Specify Output Directory: plantuml -txt -o ./docs/diagrams diagram.puml
Batch Processing: plantuml -txt ./src/diagrams/ (Processes all files in the folder)
Character Set: plantuml -txt -charset UTF-8 diagram.puml

Troubleshooting

Alignment Issues: Always view ASCII diagrams in a fixed-width font (like Courier, Consolas, or Monaco). Variable-width fonts will break the diagram structure.
Garbled Characters: If using -utxt, ensure your terminal emulator is configured to support UTF-8 encoding.
Complexity Limits: ASCII art has limited resolution. For extremely large diagrams, consider breaking them into smaller, modular components for better readability.