{"id":6460,"library":"sphinxcontrib-plantuml","title":"Sphinx PlantUML Extension","description":"sphinxcontrib-plantuml is a Sphinx extension that enables the embedding of PlantUML diagrams directly into reStructuredText or Markdown documentation. It translates PlantUML text blocks into image files (PNG, SVG, PDF) during the Sphinx build process. The current version is 0.31, and the project maintains a fairly active release cadence, with multiple updates in recent years.","status":"active","version":"0.31","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/plantuml/","tags":["sphinx","documentation","uml","diagrams","plantuml","extension"],"install":[{"cmd":"pip install sphinxcontrib-plantuml","lang":"bash","label":"Install the Python package"}],"dependencies":[{"reason":"Required Java application for rendering diagrams. Must be installed separately and accessible via PATH or configured in conf.py.","package":"PlantUML","optional":false},{"reason":"Required to run PlantUML. Must be installed separately.","package":"Java Runtime Environment (JRE)","optional":false}],"imports":[{"note":"To enable the extension, add 'sphinxcontrib.plantuml' to the 'extensions' list in your Sphinx conf.py file.","symbol":"sphinxcontrib.plantuml","correct":"extensions = ['sphinxcontrib.plantuml']"}],"quickstart":{"code":"# conf.py\nimport os\n\nproject = 'My Project'\ncopyright = '2026, Your Name'\nextensions = [\n    'sphinxcontrib.plantuml',\n]\n\n# Configure PlantUML executable path (essential if not in PATH)\n# Replace '/path/to/plantuml.jar' with the actual path.\n# If 'plantuml' command is in your system PATH, this line can be omitted.\n# plantuml = 'java -jar /path/to/plantuml.jar'\n\n# Optional: Set output format (default is 'png' for HTML)\n# plantuml_output_format = 'svg_img'\n\n# index.rst (or a new .rst file)\n# Add the following to your .rst file:\n# .. uml::\n#    @startuml\n#    Alice -> Bob: Hello\n#    Bob -> Alice: Hi!\n#    @enduml\n\n# To build the documentation:\n# sphinx-build -b html . _build/html","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.20.1 and potentially other versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"deprecated","affected_versions":"< 0.28 (Sphinx 4.x issues), potentially older versions for Python 3.13"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}