Sphinxcontrib-BibTeX

2.6.5 · active · verified Sun Apr 12

Sphinxcontrib-bibtex is a Sphinx extension that enables BibTeX-style citations in documentation. It allows users to insert citations via roles like `:cite:p:` and `:cite:t:` and generate bibliographies using a `.. bibliography::` directive, similar to LaTeX's `thebibliography` environment. The library is currently at version 2.6.5 and maintains an active development and release cadence.

Warnings

breaking As of version 2.6.0, Sphinx versions 2.x and lower are no longer supported. The minimum required Sphinx version is now 3.5.
Fix: Upgrade your Sphinx installation to version 3.5 or higher (`pip install 'Sphinx>=3.5'`).
breaking As of version 2.6.0, Python 3.6 is no longer officially supported. The library now requires Python 3.9 or newer.
Fix: Upgrade your Python environment to Python 3.9 or a newer supported version.
breaking Versions 0.18 and 0.19 of `docutils` are explicitly excluded due to known issues causing spurious `div` tags in HTML output.
Fix: Ensure `docutils` is not version 0.18 or 0.19. The `pyproject.toml` specifies `docutils>=0.8,!=0.18.*,!=0.19.*`.
gotcha Failing to configure the `bibtex_bibfiles` setting in `conf.py` will result in an `ExtensionError` when Sphinx builds the documentation.
Fix: Always define `bibtex_bibfiles = ['your_file.bib']` (or a list of files) in your `conf.py`.
gotcha Prior to version 2.2.0, only a single `:cite:` role was available. Version 2.2.0 introduced distinct roles like `:cite:t:` (textual) and `:cite:p:` (parenthetical) for better control over citation formatting.
Fix: For enhanced citation styling and new features, upgrade to `sphinxcontrib-bibtex` 2.2.0 or newer and use the specific `cite:t:` and `cite:p:` roles.
gotcha Users often encounter 'Could not import extension sphinxcontrib.bibtex' errors, usually stemming from an environment mismatch between where `sphinxcontrib-bibtex` is installed and where `sphinx-build` is executed.
Fix: Ensure that `pip install sphinxcontrib-bibtex` is run in the same Python environment that is used to execute `sphinx-build`. Verify with `which python` and `which sphinx-build`.

Install

pip install sphinxcontrib-bibtex Install with pip

Imports

sphinxcontrib.bibtex
```
extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.bibtex'
]
```
The extension is enabled by adding 'sphinxcontrib.bibtex' to the `extensions` list in your Sphinx `conf.py` file.

Quickstart

To quickly set up `sphinxcontrib-bibtex`, first install it via pip. Then, modify your `conf.py` to add `'sphinxcontrib.bibtex'` to your `extensions` list and specify your BibTeX files using `bibtex_bibfiles`. Create a `.bib` file (e.g., `refs.bib`) with your entries. Finally, use `:cite:t:` (textual), `:cite:p:` (parenthetical) roles, and the `.. bibliography::` directive in your reStructuredText files to cite and display your references.

# conf.py
import os
import sys

project = 'My Project'
copyright = '2026, Author'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.bibtex',
]

# Configure paths to your BibTeX files
bibtex_bibfiles = ['refs.bib']

# Optional: Set a default referencing style (e.g., 'author_year')
# bibtex_reference_style = 'author_year'

# index.rst (or any .rst file)
"""
.. _index:

Welcome to My Project's Documentation!
======================================

This is a demonstration of ``sphinxcontrib-bibtex``.

Here's a textual citation: See :cite:t:`1987:nelson` for an introduction to non-standard analysis.
And here's a parenthetical one: Non-standard analysis is fun :cite:p:`1987:nelson`.

References
----------

.. bibliography::
   :all:
   :max_citation_text_length: 80
"""

# refs.bib
"""
@Book{1987:nelson,
  author = {Edward Nelson},
  title = {Radically Elementary Probability Theory},
  publisher = {Princeton University Press},
  year = {1987}
}
"""

view raw JSON →