Registry / web-framework / sphinxcontrib-bibtex

sphinxcontrib-bibtex

library2.7.0pypypi✓ verified 22d ago

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.

web-framework data serialization

pip install sphinxcontrib-bibtex

github ↗package ↗

INSTALL

IMPORT

SIG · SPHINXCONTRIB-BIBT

sphinxcontrib-bibtex

web-frameworkpythonv2.7.0

Install

5.8s avg

Import

—

Disk

99MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.7.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 · 96.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.8s · import 0.000s · 97MB

99MB installed

● package 99MB

Code

Verified usage

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

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.

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} } """

Debug

Known issues

breakingAs 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'`).

affects: >=2.6.0

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

affects: >=2.6.0

breakingVersions 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.*`.

affects: >=2.6.0

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

affects: All versions

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

affects: <2.2.0

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

affects: All versions

Upgrade

Version history

2.7.0latest on PyPI · released May 6, 2026

Audit

Dependencies

SphinxrequiredRequired as it's a Sphinx extension.

docutilsrequiredUnderlying documentation utility for Sphinx.

pybtexrequiredUsed for BibTeX formatting.

pybtex-docutilsrequiredDocutils backend for pybtex.

importlib_metadataoptionalBackport of importlib.metadata for Python versions earlier than 3.10, although its role has diminished with Python >=3.9 requirement.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mcmtroffaes/sphinxcontrib-bibtex ↗

packagehttps://pypi.org/project/sphinxcontrib-bibtex/ ↗