breathe

library4.36.0pypypi✓ verified 23d ago

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.

web-framework

pip install breathe

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · BREATHE

breathe

web-frameworkpythonv4.36.0

Install

5.5s avg

Import

—

Disk

96MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.36.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 93.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.5s · import 0.000s · 94MB

96MB installed

● package 96MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

breathe

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

✗ import 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.

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

Debug

Known issues

breakingBreathe 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.

affects: >=4.36.0

breakingBreathe 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.

affects: >=4.36.0

gotchaBreathe 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`.

affects: All versions

gotchaIncorrectly 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`.

affects: All versions

gotchaWhile 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.

affects: All versions

Upgrade

Version history

4.36.0latest on PyPI · released Feb 22, 2025

Audit

Dependencies

pythonrequiredRuntime environment.

sphinxrequiredCore dependency as a Sphinx extension.

doxygenrequiredRequired to generate the XML output that Breathe consumes.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/breathe-doc/breathe ↗

packagehttps://pypi.org/project/breathe/ ↗

homepagehttps://www.breathe-doc.org/ ↗

docshttps://breathe.readthedocs.io/ ↗

changeloghttps://github.com/breathe-doc/breathe/blob/main/CHANGELOG.rst ↗