Breathe

4.36.0 · active · verified Sat Apr 11

Breathe is a Sphinx plugin that provides a bridge between the Sphinx documentation system and Doxygen's XML output. It allows users to integrate Doxygen's comprehensive technical documentation of C, C++, and other languages directly into Sphinx-generated documentation, offering an 'autodoc'-like experience for non-Python projects. The current stable version is 4.36.0, with releases typically occurring a few times a year to maintain compatibility with Sphinx and Doxygen updates.

Warnings

breaking Breathe v4.36.0 and later require Python 3.9 or higher. Earlier versions supported Python 3.7+ (e.g., v4.35.0). Projects on older Python versions will need to upgrade Python or pin Breathe to an older compatible version.
Fix: Upgrade Python to 3.9+ or pin `breathe<4.36.0` (e.g., `breathe==4.35.0`) if Python upgrade is not feasible.
breaking Breathe v4.36.0 and later require Sphinx 7.2 or higher. Earlier versions had compatibility with older Sphinx versions (e.g., v4.35.0 added support for Sphinx 6, fixed tests for Sphinx 5.3). Ensure your Sphinx installation meets this requirement.
Fix: Upgrade Sphinx to 7.2+ or pin `breathe` and `sphinx` to mutually compatible older versions.
gotcha Breathe relies entirely on Doxygen's XML output. If Doxygen is not run correctly with `GENERATE_XML = YES` enabled in its configuration file (Doxyfile), Breathe will not find any documentation to render.
Fix: Ensure your Doxyfile contains `GENERATE_XML = YES` and that Doxygen is run to produce the XML files in the directory specified by `breathe_projects`.
gotcha Incorrectly configured `breathe_projects` paths or `breathe_default_project` names are common sources of 'project not found' or 'file not found' errors. The paths must be absolute or correctly relative to `conf.py`.
Fix: Double-check that the paths in `breathe_projects` correctly point to the Doxygen XML output directories and that the project names used in directives (e.g., `:project: myproject`) match the keys in `breathe_projects`.
gotcha While v4.36.0 is the current stable release, alpha versions like `v5.0.0a2` are available. Installing without version pinning (`pip install breathe`) may lead to unexpected changes or instabilities if a new major alpha becomes the 'latest' on PyPI.
Fix: Always pin to a specific major/minor version (e.g., `pip install 'breathe<5'`) or a precise version (`pip install breathe==4.36.0`) to avoid inadvertently upgrading to pre-release versions.

Install

pip install breathe Install stable version

Imports

breathe
```
extensions = ['sphinx.ext.autodoc', 'breathe']
```
Breathe is a Sphinx extension, not a Python module imported directly in user code for typical usage. It is activated by adding 'breathe' to the 'extensions' list in Sphinx's conf.py.

Quickstart

To use Breathe, first configure Doxygen to generate XML output (`GENERATE_XML = YES`). Then, in your Sphinx `conf.py`, add `breathe` to your `extensions` list and configure `breathe_projects` to point to your Doxygen XML output directory. Finally, use Breathe's reStructuredText directives (e.g., `.. doxygenclass::`, `.. doxygenfunction::`) in your `.rst` files to include the Doxygen documentation.

# 1. In your Doxyfile (generated by Doxygen -g), ensure:
#    GENERATE_XML = YES
# 2. In your Sphinx conf.py:
import os

project = 'MyProject'
copyright = '2026, MyName'
author = 'MyName'

extensions = [
    'sphinx.ext.autodoc',
    'breathe'
]

# Path to the directory containing Doxygen's XML output
breathe_projects = {
    "myproject": os.path.abspath(os.path.join(os.path.dirname(__file__), "_build/doxygen/xml"))
}

breathe_default_project = "myproject"

# 3. In an .rst file (e.g., index.rst or a new file like api.rst):
# .. doxygenclass:: MyNamespace::MyClass
#    :project: myproject
#    :members:
#
# .. doxygenfunction:: my_function(int, int)
#    :project: myproject

view raw JSON →