Sphinx PlantUML Extension

Warnings

• breaking The `sphinxcontrib-plantuml` extension itself is merely a Python wrapper for Sphinx. It *requires* PlantUML (the Java application) and a Java Runtime Environment (JRE) to be installed separately on the system where Sphinx builds are performed. Without these, diagrams cannot be rendered, leading to build failures or 'unknown directive' errors.
  Fix: Install PlantUML and a compatible JRE. Download `plantuml.jar` from the official PlantUML website and install Java (e.g., OpenJDK). Ensure the `java` command and `plantuml.jar` are accessible.
• gotcha If the `plantuml` command is not in your system's PATH, you must explicitly configure its full command in `conf.py`. Failing to do so will result in Sphinx being unable to find and execute PlantUML.
  Fix: Add `plantuml = 'java -jar /path/to/plantuml.jar'` to your `conf.py`, replacing `/path/to/plantuml.jar` with the actual location of the PlantUML executable JAR file.
• gotcha PlantUML can sometimes silently fall back to generating PNG images, even when another format (like SVG) is requested, for example, when certain diagram types (e.g., ditaa) are included. This silent fallback can cause unexpected encoding errors in `sphinxcontrib-plantuml` if it expects a specific output format.
  Fix: Explicitly define the expected output format using `plantuml_output_format` and ensure your PlantUML code is compatible with the desired output. Check PlantUML's own error logs for issues with diagram generation.
• gotcha For HTML output, the default `plantuml_output_format` is `png`. If using SVG, `svg_obj` (embedding with `<object/>`) might lead to scaling issues in some browsers. For better responsiveness, `svg_img` (embedding with `<img/>`) is often preferred. For LaTeX/PDF output, `png` quality can be poor; `svg_pdf` (requires `sphinxcontrib-svg2pdfconverter` or similar) or `eps_pdf` (requires `epstopdf`) is recommended.
  Fix: Set `plantuml_output_format = 'svg_img'` in `conf.py` for responsive SVG in HTML. For high-quality PDF, configure `plantuml_latex_output_format = 'pdf'` (which uses `svg_pdf` or `eps_pdf` if converters are available) and ensure necessary converters like `sphinxcontrib-svg2pdfconverter` or `epstopdf` are installed.
• deprecated Older versions of `sphinxcontrib-plantuml` had compatibility issues with newer Sphinx 4.x releases and Python 3.13 due to internal API changes in Sphinx and Python's `inspect` module.
  Fix: Always use the latest stable version of `sphinxcontrib-plantuml` (0.31 or newer) to ensure compatibility with recent Sphinx and Python releases. Upgrade `pip install --upgrade sphinxcontrib-plantuml`.

Install

• pip install sphinxcontrib-plantuml Install the Python package

Imports

• sphinxcontrib.plantuml

  extensions = ['sphinxcontrib.plantuml']

  To enable the extension, add 'sphinxcontrib.plantuml' to the 'extensions' list in your Sphinx conf.py file.

Quickstart

To quickly get started, first, create a Sphinx project. Then, modify your `conf.py` to include `sphinxcontrib.plantuml` in your `extensions` list. Crucially, ensure that the PlantUML Java executable is either in your system's PATH or explicitly configured using the `plantuml` variable in `conf.py`. Finally, embed PlantUML code directly into your reStructuredText files using the `.. uml::` directive.

# conf.py
import os

project = 'My Project'
copyright = '2026, Your Name'
extensions = [
    'sphinxcontrib.plantuml',
]

# Configure PlantUML executable path (essential if not in PATH)
# Replace '/path/to/plantuml.jar' with the actual path.
# If 'plantuml' command is in your system PATH, this line can be omitted.
# plantuml = 'java -jar /path/to/plantuml.jar'

# Optional: Set output format (default is 'png' for HTML)
# plantuml_output_format = 'svg_img'

# index.rst (or a new .rst file)
# Add the following to your .rst file:
# .. uml::
#    @startuml
#    Alice -> Bob: Hello
#    Bob -> Alice: Hi!
#    @enduml

# To build the documentation:
# sphinx-build -b html . _build/html