{"id":5064,"library":"sphinxcontrib-bibtex","title":"Sphinxcontrib-BibTeX","description":"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.","status":"active","version":"2.6.5","language":"en","source_language":"en","source_url":"https://github.com/mcmtroffaes/sphinxcontrib-bibtex","tags":["sphinx","documentation","bibtex","citations","technical-writing"],"install":[{"cmd":"pip install sphinxcontrib-bibtex","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required as it's a Sphinx extension.","package":"Sphinx","version":">=3.5"},{"reason":"Underlying documentation utility for Sphinx.","package":"docutils","version":">=0.8,!=0.18.*,!=0.19.*"},{"reason":"Used for BibTeX formatting.","package":"pybtex","version":">=0.25"},{"reason":"Docutils backend for pybtex.","package":"pybtex-docutils","version":">=1.0.2"},{"reason":"Backport of importlib.metadata for Python versions earlier than 3.10, although its role has diminished with Python >=3.9 requirement.","package":"importlib_metadata","version":">=3.6","optional":true}],"imports":[{"note":"The extension is enabled by adding 'sphinxcontrib.bibtex' to the `extensions` list in your Sphinx `conf.py` file.","symbol":"sphinxcontrib.bibtex","correct":"extensions = [\n    'sphinx.ext.autodoc',\n    'sphinxcontrib.bibtex'\n]"}],"quickstart":{"code":"# conf.py\nimport os\nimport sys\n\nproject = 'My Project'\ncopyright = '2026, Author'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.bibtex',\n]\n\n# Configure paths to your BibTeX files\nbibtex_bibfiles = ['refs.bib']\n\n# Optional: Set a default referencing style (e.g., 'author_year')\n# bibtex_reference_style = 'author_year'\n\n# index.rst (or any .rst file)\n\"\"\"\n.. _index:\n\nWelcome to My Project's Documentation!\n======================================\n\nThis is a demonstration of ``sphinxcontrib-bibtex``.\n\nHere's a textual citation: See :cite:t:`1987:nelson` for an introduction to non-standard analysis.\nAnd here's a parenthetical one: Non-standard analysis is fun :cite:p:`1987:nelson`.\n\nReferences\n----------\n\n.. bibliography::\n   :all:\n   :max_citation_text_length: 80\n\"\"\"\n\n# refs.bib\n\"\"\"\n@Book{1987:nelson,\n  author = {Edward Nelson},\n  title = {Radically Elementary Probability Theory},\n  publisher = {Princeton University Press},\n  year = {1987}\n}\n\"\"\"","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Sphinx installation to version 3.5 or higher (`pip install 'Sphinx>=3.5'`).","message":"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.","severity":"breaking","affected_versions":">=2.6.0"},{"fix":"Upgrade your Python environment to Python 3.9 or a newer supported version.","message":"As of version 2.6.0, Python 3.6 is no longer officially supported. The library now requires Python 3.9 or newer.","severity":"breaking","affected_versions":">=2.6.0"},{"fix":"Ensure `docutils` is not version 0.18 or 0.19. The `pyproject.toml` specifies `docutils>=0.8,!=0.18.*,!=0.19.*`.","message":"Versions 0.18 and 0.19 of `docutils` are explicitly excluded due to known issues causing spurious `div` tags in HTML output.","severity":"breaking","affected_versions":">=2.6.0"},{"fix":"Always define `bibtex_bibfiles = ['your_file.bib']` (or a list of files) in your `conf.py`.","message":"Failing to configure the `bibtex_bibfiles` setting in `conf.py` will result in an `ExtensionError` when Sphinx builds the documentation.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.2.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}