Sphinx SVG to PDF or PNG Converter Extension

2.1.0 · active · verified Mon Apr 13

This extension converts SVG images to PDF or PNG when Sphinx builders do not natively support SVG images (e.g., LaTeX). It leverages external tools like Inkscape, rsvg-convert (from libRSVG), or CairoSVG for the conversion. The library is currently at version 2.1.0 and is actively maintained with updates released as needed to support Sphinx versions and conversion tools.

Warnings

gotcha This library acts as a wrapper around external tools (Inkscape, rsvg-convert, or CairoSVG). You must install these underlying conversion tools and ensure they are accessible in your system's PATH, or configure their paths in `conf.py`. The `[CairoSVG]` extra will install the Python `cairosvg` package, but `cairosvg` itself has system dependencies (like `libcairo`) that are not automatically handled by `pip`.
Fix: Install Inkscape, `librsvg2-bin` (for `rsvg-convert`), or `cairosvg` and its system dependencies. Configure `inkscape_converter_bin`, `rsvg_converter_bin` if tools are not in PATH. Consult CairoSVG documentation for its system dependencies.
gotcha The choice of conversion backend (Inkscape, rsvg-convert, or CairoSVG) is determined by which specific extension you add to your `conf.py`'s `extensions` list (e.g., `sphinxcontrib.inkscapeconverter`, `sphinxcontrib.rsvgconverter`, `sphinxcontrib.cairosvgconverter`). There is no single `sphinxcontrib.svg2pdfconverter` entry to configure the backend.
Fix: Add only one of `sphinxcontrib.inkscapeconverter`, `sphinxcontrib.rsvgconverter`, or `sphinxcontrib.cairosvgconverter` to your `conf.py` `extensions` list.
breaking Support for converting SVG images to PNG (in addition to PDF) was added in version 2.0.0. If your project requires PNG output, ensure you are using `sphinxcontrib-svg2pdfconverter` version 2.0.0 or newer.
Fix: Upgrade to version 2.0.0 or later: `pip install --upgrade sphinxcontrib-svg2pdfconverter`.
gotcha When using the `rsvgconverter` backend, specifying `rsvg_converter_format = 'pdf1.5'` in `conf.py` is recommended. This format often generates fewer warnings and offers better compatibility with LaTeX backends, especially with newer versions of `rsvg-convert`.
Fix: Add `rsvg_converter_format = 'pdf1.5'` to your `conf.py` if using `sphinxcontrib.rsvgconverter`.

Install

pip install sphinxcontrib-svg2pdfconverter Basic Installation
pip install sphinxcontrib-svg2pdfconverter[CairoSVG] With CairoSVG Backend

Imports

Extension Activation
```
extensions = ['sphinxcontrib.inkscapeconverter'] # or .rsvgconverter, .cairosvgconverter
```
The extension is enabled by adding its module name as a string to the `extensions` list in Sphinx's `conf.py`, not by directly importing a Python class.

Quickstart

To use `sphinxcontrib-svg2pdfconverter`, you enable one of its backend-specific extensions in your Sphinx project's `conf.py` file. This example uses `cairosvgconverter`, which is often the easiest to set up due to its Pythonic nature, but still requires `libcairo` on the system. Remember to install the `[CairoSVG]` extra for `cairosvg`.

# conf.py
import os
import sys

sys.path.insert(0, os.path.abspath('.'))

project = 'My Sphinx Project'
copyright = '2026, Your Name'
author = 'Your Name'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.cairosvgconverter', # Choose your backend: inkscapeconverter, rsvgconverter, or cairosvgconverter
]

# Example: Configure path for Inkscape if not in PATH (uncomment and adjust as needed)
# inkscape_converter_bin = '/usr/local/bin/inkscape'

# Example: Configure rsvg-convert (uncomment and adjust as needed)
# rsvg_converter_bin = '/usr/bin/rsvg-convert'
# rsvg_converter_format = 'pdf1.5' # Recommended for LaTeX compatibility

view raw JSON →