sphinxcontrib-drawio

What it is and what it does

sphinxcontrib-drawio is a Sphinx extension that lets you include draw.io diagrams directly in your documentation source. Instead of manually exporting diagrams to PNG or SVG and committing static images, you reference .drawio files in your reStructuredText using the drawio-image or drawio-figure directives, and the extension automatically exports them to your chosen format during the Sphinx build. It wraps the draw.io CLI tool and handles the mechanics of invoking it with the right options.

The extension is designed for projects that maintain diagrams in draw.io's native format and want those diagrams to stay in version control alongside the documentation source. It supports per-diagram export settings (format, scale, transparency, page selection) and builder-specific defaults, so you can export to SVG for HTML builds and PDF for LaTeX builds without duplicating directives. The main constraint is that it requires the draw.io desktop binary to be installed on the build machine, and on headless systems (CI, Docker) you need to configure virtual framebuffer support.

Use it for:

• Maintain architecture diagrams, flowcharts, and UX mockups in draw.io and auto-export them to your Sphinx HTML/PDF documentation on each build.
• Configure different export formats per Sphinx builder (SVG for web, PDF for print) without editing source files.
• Scale diagrams to higher resolution for print output using the export-scale option.
• Include multi-page draw.io files and select specific pages by index or name for different sections of your docs.
• Run diagram export in CI/CD pipelines with headless mode and Xvfb for automated documentation builds.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that embeds draw.io diagrams into documentation by converting .drawio files to image formats (PNG, JPG, SVG, PDF) during the build process.

Yes, if you actively maintain diagrams in draw.io and want them version-controlled and auto-exported in your Sphinx docs. The extension is stable, actively maintained, has no security issues, and low install friction. The main gotcha is the external draw.io binary dependency and headless-mode setup on CI—plan for that upfront. Not suitable for Read the Docs hosting.

Install

sphinxcontrib-drawio on PyPI

pip install sphinxcontrib-drawio

uv add sphinxcontrib-drawio

poetry add sphinxcontrib-drawio

Installing sphinxcontrib-drawio

Before you install

Low friction: pure Python wheel with only sphinx as a runtime dependency. Active maintenance (last commit 2026-04-13) with no recent security issues. Requires the draw.io desktop binary in PATH and Xvfb on headless systems, which are external system dependencies, not Python-level friction.

License in practice

MIT license (permissive) means you can use, modify, and distribute this extension freely in both open and closed projects with minimal restrictions.

Quickstart

pip install sphinxcontrib-drawio

# In conf.py:
extensions = ["sphinxcontrib.drawio"]

# In your .rst file:
.. drawio-image:: example.drawio
   :export-scale: 150

The draw.io desktop binary must be installed and accessible in $PATH (or configured via drawio_binary_path). On headless/CI systems, Xvfb must be installed and drawio_headless set to 'auto' or True. Does not work on Read the Docs due to RTD's restrictions on external packages.

Verify before relying

• Whether the extension handles multi-page .drawio files reliably when page-index or page-name options are used.
• Performance impact when exporting many large diagrams in a single documentation build.
• Compatibility with recent versions of draw.io desktop (last release was 2023-09-12).

Package facts

Evidence: sphinxcontrib_drawio-0.0.17-py3-none-any.whl

Tags

More Sphinx packages