Support via Liberapay

PlantUML Code Blocks in Babel

Babel support for PlantUML


PlantUML is a Java component for creating Unified Modeling Language (UML) diagrams and several non-UML diagrams with a simple language. Diagram images can be generated in PNG, SVG, and LaTeX formats.

PlantUML is integrated with a wide variety of software applications. Babel is a standard way to use PlantUML in Emacs.

Requirements and Setup

PlantUML blocks can be executed in one of two ways, requiring either

  • a working Java installation and access to the plantuml.jar component or
  • the plantuml executable available from your distribution's package manager

A working GraphViz installation is required for many diagrams.

Emacs has plantuml-mode, a major mode for editing PlantUML sources. There are detailed installation instructions, as well as instructions for integration with Org. While plantuml-mode does allow use of a remote server to render the diagram, please note that ob-plantuml does not currently support this functionality.

You will likely want to set the variables plantuml-jar-path and org-plantuml-jar-path with the path to your local installation of PlantUML. Alternatively, set the variable plantuml-default-exec-mode to executable to use your local plantuml executable.

Activate evaluation of PlantUML source code blocks by adding plantuml to org-babel-load-languages.

 '((plantuml . t))) ; this line activates plantuml

Babel Features for PlantUML Code Blocks

Header Arguments

PlantUML code blocks default to :results file and :exports results.

If you wish to export the PlantUML code block to a file, you must specify a :file header argument. Alternatively, if you set :results to a value other than file, such as :results verbatim, then the ASCII PlantUML output will be inserted into the buffer below the code block.

PlantUML has these language-specific header arguments:

specify command line arguments for PlantUML
arguments for the java runtimes (JRE)


PlantUML does not support sessions.

Result Types

When the :file header argument has been specified, PlantUML code blocks return a link to the generated file. Alternatively, if :results is set to a value other than file, then the generated ASCII diagram will be inserted into the buffer.

Examples of Use

Here is the obligatory Hello World! example in PlantUML.

The PlantUML code block in the Org buffer:

#+begin_src plantuml :file images/hello-uml.png
Bob -> Alice : Hello World!

HTML output of the PlantUML code block:

Bob -> Alice : Hello World!
Figure 1: The PNG Hello World! image.

Here is an example using a theme.

The PlantUML code block in the Org buffer:

#+begin_src plantuml :file images/theme-uml.png
!theme spacelab
a -> b
b -> c

PNG output of the PlantUML code block:

!theme spacelab
a -> b
b -> c
Figure 2: The themed PNG image.

Here is an example of ASCII output inserted directly into the buffer.

The PlantUML code block in the Org buffer:

#+begin_src plantuml :results verbatim
Bob -> Alice : Hello World!

ASCII output of the PlantUML code block:

,---.          ,-----.
|Bob|          |Alice|
`-+-'          `--+--'
  | Hello World!  |   
,-+-.          ,--+--.
|Bob|          |Alice|
`---'          `-----'

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.