plantuml-mode: writing PlantUML inside Emacs, with a privacy decision attached

A major mode, and what it adds to a text editor

plantuml-mode is a PlantUML major mode for Emacs, written in Emacs Lisp and distributed under the GPL-3 licence. The homepage is the PlantUML project itself, and the package is published on MELPA with a badge for the stable channel as well.

The feature list is short and each item is a real convenience rather than a feature for its own sake. Syntax highlight. Autocompletion. Preview of the buffer or of a selected region. The choice of using either a local JAR or a remote server for the preview. And the ability to set a default custom theme, unless one is explicitly set in the diagram source.

That last point is worth pausing on, because it is the difference between a diagram that looks the way your project expects and one that inherits whatever the public server defaults to. The theme is a rendering parameter, and the mode lets you fix it once for the project.

The audience is specific. It is for a person who writes PlantUML as text and lives in Emacs, and who wants the diagram to appear while they type rather than in a separate browser tab and a separate render step. The mode is a convenience layer over the PlantUML tool itself, and the interesting part is not the editing but how it decides where to render.

The repository is a single Lisp file, plantuml-mode.el, with a Cask file for the Emacs package build, a Makefile, a compose file for the test server, a test directory and a bin directory.

The quick guide, and the warning about sending diagrams to a server

The quick guide is three keystrokes and a preview, and it is short enough that the warning beside it is easy to skim past.

You install with the package command, enable the mode for the current buffer, write your PlantUML source, and preview the diagram with the C-c C-c key sequence, which runs plantuml-preview.

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

Then there is the warning, and it is the most consequential line in the readme. The preview may send information to https://www.plantuml.com/plantuml, and the instruction is to check that plantuml-default-exec-mode is configured correctly for your use case before previewing any sensitive material.

A diagram is not a passive text file. A class diagram contains your class names, a sequence diagram contains your service names and call patterns, and a deployment diagram contains hostnames. Sending those to a public rendering service is a disclosure decision, and the mode makes that decision on your behalf unless you make it yourself.

The configuration that controls it is short.

    ;; Sample jar configuration
    (setq plantuml-jar-path "/path/to/your/copy/of/plantuml.jar")
    (setq plantuml-default-exec-mode 'jar)

    ;; Sample executable configuration
    (setq plantuml-executable-path "/path/to/your/copy/of/plantuml.bin")
    (setq plantuml-default-exec-mode 'executable)

Two variables decide everything: the path to a local JAR, and the mode. The readme points at the execution modes section for the detail, and that section is the one to read before you render anything.

Three execution modes, and one of them is marked experimental

The execution modes section is headed EXPERIMENTAL, and says that as of v1.3.0 support was added for switching execution mode. Three modes are listed.

The jar mode is described as the traditional system, running PlantUML as a local JAR file, and it is the traditional system used by plantuml-mode. The server mode is the default, and it lets an instance of plantuml-server do the rendering. The third bullet, describing the executable mode, is cut off in the version of the readme we have, but the configuration sample and the variable list make its shape clear: plantuml-executable-path points at a plantuml executable file and plantuml-executable-args passes arguments to it.

So the choice is between three sources of the rendering. A local JAR needs a Java runtime and a jar file on disk. A local executable needs a native binary. A server needs a reachable PlantUML server, either your own or the public one, and it is what the mode uses unless you say otherwise.

The server mode has one setting worth understanding, and it is plantuml-server-encode-mode. You can generate the URL by compressing with deflate, which is better for the network, or by encoding with hex, which is better for CPU usage, and the readme links the official PlantUML documentation for text encoding. That is a small window into how the mode works: the diagram source is encoded into the request URL, so a long diagram produces a long URL, and the encoding trades bandwidth against processing.

The rest of the variables are ordinary customisation: plantuml-java-command and plantuml-java-args for the JAR path, plantuml-server-url for the server path, plantuml-output-type to force svg, png or txt, plantuml-indent-level, plantuml-preview-default-theme, plantuml-svg-background to force a background colour or leave the default transparent one, and plantuml-suppress-deprecation-warning to silence the warning if the deprecated puml-mode is found.

Installing from MELPA and pointing the mode at a JAR

Installation assumes MELPA is enabled in your emacs.d, and then it is the usual package dance.

    M-x package-install<RET>
    plantuml-mode<RET>

Enabling the mode for the current buffer is the command M-x plantuml-mode, and the readme shows how to have it happen automatically for files with the .plantuml extension by adding an entry to auto-mode-alist in your .emacsrc.

    ;; Enable plantuml-mode for PlantUML files
    (add-to-list 'auto-mode-alist '("\\.plantuml\\'" . plantuml-mode))

The part that is specific to this mode is finding PlantUML itself. To enable the preview you have to tell the mode where the PlantUML JAR file is. By default it looks for the file in ~/plantuml.jar, and you can point it anywhere with the customise command and the plantuml-jar-path variable.

    M-x customize-variable<RET>
    plantuml-jar-path<RET>

There is also a command that removes that step entirely. The plantuml-download-jar command downloads the latest version of PlantUML straight into plantuml-jar-path, and it arrived in the v.1.2.11 release, whose title is the easier first setup with that command.

The developer side of the repository follows the same shape. The Makefile exports a cask binary and an emacs binary, runs the test suite in batch mode against a local init file, and splits the tests into unit and integration, where the unit target excludes the server tests and the integration target runs them.

Previewing, the key bindings, and org-mode

The preview command is M-x plantuml-preview, and it renders the diagram in a buffer called *PLANTUML-Preview*. The output format is chosen automatically from what your Emacs supports, in a stated order of preference: SVG, then PNG, then Unicode ASCII art. The last of those is a deliberate fallback for a terminal only setup.

What gets rendered is the selected region if there is one in the current buffer, and the whole buffer otherwise. If you want a specific format regardless of what Emacs supports, you set plantuml-output-type to the value you prefer.

The default key bindings are three.

    C-c C-c  plantuml-preview: renders a PlantUML diagram from the current buffer in the best supported format

    C-u C-c C-c  plantuml-preview in other window

    C-u C-u C-c C-c plantuml-preview in other frame

The two prefixed variants exist so you can send the preview to another window or another frame, which is the difference between a preview you can read next to your source and one that replaces what you were looking at.

The org-mode integration is the part that makes this useful inside a larger document. You register the language with the org-src-lang-modes list, and then a plantuml code block in an org file can be edited in the mode with C-c ' while inside the block, and C-' takes you back to the original org document.

#+BEGIN_SRC plantuml
  <hit C-c ' here to open a plantuml-mode buffer>
#+END_SRC

Completion is the other half of the editing experience. The plantuml-complete-symbol command opens a popup with the available completions, taken from the keyword list that PlantUML itself reports when run with the -language flag, so the completion list follows the version of PlantUML you have rather than a list frozen into the Lisp.

Where plantuml-mode is the wrong tool

Four limits, and the first is the one the readme itself raises.

The default execution mode is server, which means the default behaviour of a preview is to send your diagram somewhere. For a diagram of a personal to-do list that is irrelevant, and for a class diagram of a proprietary system it is a disclosure you did not intend. The mode gives you the tools to avoid it, and a configuration variable to select a local JAR or a local executable, but the default is the network path, and a user who never touches the configuration will send their diagrams to a public service without realising it.

The second is that the execution mode support is labelled experimental. The modes were added in v1.3.0, and the published releases in the list are from 2019, so the mode of the code you get from MELPA Stable may not be the mode the current development branch has. Switching between jar, server and executable is a feature that the documentation is still catching up with.

The third is the age of the releases. The most recent tags are v1.4.0 and v1.3.1, both on 2019-08-21, and v.1.2.11 in May 2019, while the last push to the default branch was on 2026-05-14. Work is landing on the develop branch without a new release, so the packaged version in MELPA may lag the code by a long time.

The fourth is scope. The mode edits and previews PlantUML. It does not generate diagrams from other tools, it does not integrate with a documentation build, and it does not manage PlantUML versions for you beyond the download command.

Licence, testing setup and the state of the repository

The licence is GPL-3, with the licence file named LICENSE.txt at the root of the repository, so the code can be used, modified and redistributed with the notice kept. This is not legal advice.

The test infrastructure is worth a look, because it explains how the three execution modes are exercised. The compose file at the root of the repository starts a PlantUML server for the tests.

services:
  plantuml-server:
    image: plantuml/plantuml-server:jetty
    container_name: plantuml-mode-test-server
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/"]
      interval: 2s
      timeout: 3s
      retries: 15
      start_period: 5s

A real server, a health check with a generous retry count, and a test suite split so that the server dependent tests only run in the integration target. The project also carries CircleCI and Coveralls badges, and the repository has a .circleci directory.

The default branch is develop, which is the usual convention for a project where master holds the last release and the development line lives elsewhere, and the readme points at MELPA and MELPA Stable as the two channels.

One practical detail deserves a mention for anyone who forks the repository. The Makefile carries a Coveralls repository token as a literal value in the file. That is a common pattern in older Emacs packages, and it is a pattern worth changing in a fork, because a credential that lives in a public repository is a credential that is public.

With the last push on 2026-05-14 and the repository not archived, the mode is being worked on, but the releases you can install from MELPA are from 2019, and that gap is the thing to keep in mind when you pin a version.

Editorial conclusion

plantuml-mode is the right tool for an Emacs user who keeps PlantUML sources in a repository and wants a preview without leaving the editor, and for anyone who wants their diagrams rendered locally by a JAR or a native executable rather than by a web service. It is the wrong choice for a team whose diagrams are sensitive and whose editors are not configured with an explicit execution mode, and it is the wrong choice for a project that needs features from a newer PlantUML than the mode was written against. Before adopting, set plantuml-default-exec-mode explicitly rather than relying on the default, confirm the key bindings do not collide with the ones you already use, and read the v1.3.0 and v1.4.0 release notes, since the execution mode support is marked experimental and the published releases date from 2019.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. skuro/plantuml-mode on GitHub