pybtex

library0.26.1pypypi✓ verified 25d ago

Pybtex is a BibTeX-compatible bibliography processor written in Python, designed to read citation information from various formats (BibTeX, BibTeXML, YAML) and produce formatted bibliographies. It supports traditional BibTeX `.bst` styles and also allows for defining custom styles directly in Python, with output options including LaTeX, HTML, Markdown, or plain text. Currently at version 0.26.1, it is actively maintained and serves as a flexible alternative or drop-in replacement for the original BibTeX.

data serialization

pip install pybtex

package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYBTEX

pybtex

datapythonv0.26.1

Install

1.8s avg

Import

125ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.26.1 · 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.130s · 21.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.120s · 22MB

20MB installed

● package 20MB

Code

Verified usage

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

BibliographyData

✓ from pybtex.database import BibliographyData

Main object for holding parsed bibliography data.

Parser

✓ from pybtex.database.input.bibtex import Parser

For parsing BibTeX (.bib) files.

Writer

✓ from pybtex.database.output.html import Writer

For writing bibliography data to various output formats (e.g., HTML, LaTeX, text).

BaseStyle

✓ from pybtex.style.formatting import BaseStyle

Base class for defining custom bibliography formatting styles in Python.

Text

✓ from pybtex.richtext import Text

Used within Pythonic styles for rich text manipulation.

This quickstart demonstrates how to parse a BibTeX file, apply a predefined formatting style (or a custom one), and output the result to an HTML file using Pybtex's Python API. It creates a dummy `.bib` file, processes it, and then cleans up the generated files. For more complex use cases, especially with `.aux` files, the command-line interface or the `pybtex.Engine` might be more suitable.

from pybtex.database.input import bibtex from pybtex.database.output import html from pybtex.style.formatting import plain from pybtex.style.template import field, sentence, tag import os # Create a dummy .bib file for demonstration bib_content = """ @article{einstein1905relativity, title={Zur Elektrodynamik bewegter K\"orper}, author={Einstein, Albert}, journal={Annalen der Physik}, volume={322}, number={10}, pages={891-921}, year={1905}, doi={10.1002/andp.19053221006} } """ with open('references.bib', 'w') as f: f.write(bib_content) # 1. Parse the bibliography data parser = bibtex.Parser() bib_data = parser.parse_file('references.bib') # 2. Select a formatting style (e.g., 'plain' or a custom one) # For a custom style, you would inherit from BaseStyle style = plain.Style() # 3. Format the bibliography # The 'citations' argument specifies which entries to include. # If not provided, all entries in bib_data will be formatted. formatted_bibliography = style.format_bibliography(bib_data, citations=['einstein1905relativity']) # 4. Write the formatted bibliography to an output file (e.g., HTML) writer = html.Writer() with open('output.html', 'w') as f: writer.write_file(formatted_bibliography, f) print("Bibliography processed and saved to output.html") # Clean up dummy file os.remove('references.bib') os.remove('output.html')

pybtex --version

Debug

Known issues

gotchaPybtex uses two distinct 'engines' for bibliography formatting: a BibTeX engine (for `.bst` styles) and a Python engine (for Pythonic styles). The BibTeX engine can only output LaTeX, while the Python engine supports LaTeX, HTML, Markdown, and plain text. When using Pythonic styles, remember to specify `--style-language python` and `--output-backend <format>` via the command line or explicitly use the Python API for desired output formats.

fix

For `.bst` styles, expect LaTeX output. For HTML/Markdown/plain text output, use Pythonic styles and configure the output backend explicitly (e.g., `pybtex --style-language python --output-backend html` or use `pybtex.database.output.html.Writer` in API).

affects: All versions

gotchaWhen working with `BibliographyData` `Entry` objects in the Python API, access person-related fields (authors, editors, etc.) through the `entry.persons` dictionary, not `entry.fields`. `entry.fields` contains general string fields, while `entry.persons` holds a list of `Person` objects for each role. Additionally, `Entry` objects are not directly indexable.

fix

Use `entry.persons['author']` for authors and `entry.fields['title']` for titles. Avoid `entry[0]` as `Entry` objects do not support indexing.

affects: All versions

gotchaPybtex's strict mode behavior differs between command-line usage and library usage. By default, command-line execution prints warnings to stderr for compatibility with BibTeX, whereas programmatic use as a library will raise exceptions on all errors. This can lead to unexpected crashes if not handled.

fix

When using Pybtex programmatically, anticipate and handle `PybtexError` exceptions. For command-line use, the `--strict` option can be used to make warnings into errors.

affects: 0.18+

deprecatedThe API for reading and writing bibliography data has evolved. Earlier methods like `Entry.get_field()` were deprecated. New API for rich text and general data handling was introduced around versions 0.19 and 0.22.

fix

Consult the latest Pybtex documentation for the recommended API when reading/writing data and creating custom styles, especially for `pybtex.richtext` objects.

affects: < 0.22

Errors

Common errors & fixes

TypeError: 'Entry' object does not support indexing

This error occurs when attempting to access fields or properties of a `pybtex.database.Entry` object using list-like indexing (e.g., `entry[0]`), as `Entry` objects are not tuples and do not support this operation.

fix

Access entry properties using their specific attributes like `entry.type`, `entry.fields`, and `entry.persons`.

KeyError: 'editor'

A `KeyError` arises when trying to directly access a person role (e.g., 'editor' or 'author') from the `entry.persons` dictionary that is not present in a particular bibliography entry.

fix

Before accessing a person role, check for its existence using `if 'editor' in entry.persons:` or use the `.get()` method with a default value, e.g., `entry.persons.get('editor', [])`.

Pybtex does not recogonize bibtex entry

This issue typically occurs when the input string or file uses non-standard BibTeX syntax, such as macros from other LaTeX packages (like `amsrefs`'s `\bib` command) instead of the standard BibTeX entry types (e.g., `@article`, `@book`).

fix

Ensure that the BibTeX input adheres to standard BibTeX format (e.g., `@article{key, ...}`). If using specific LaTeX packages, the bibliography might need to be converted to standard BibTeX format before processing with Pybtex.

ModuleNotFoundError: No module named 'pybtex.database.input.bibtex'

This error indicates that the Python interpreter cannot find the specified `pybtex` submodule, often due to an incorrect import path or because the `pybtex` library itself is not installed or not accessible in the current Python environment.

fix

Verify that `pybtex` is correctly installed (`pip install pybtex`). If it is, check the import statement for typos and ensure the module path is correct according to the `pybtex` documentation, e.g., `from pybtex.database.input import bibtex`.

Upgrade

Version history

0.26.1latest on PyPI · released Apr 3, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Resources

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

homepagehttps://pybtex.org/ ↗

docshttps://docs.pybtex.org/ ↗

changeloghttps://docs.pybtex.org/history.html ↗