Skip to main content

betterbib

PyPi Version GitHub stars

Bibliography files are notoriously hard to work with. betterbib is a fast, single-binary command-line tool that helps:

Installation

Install betterbib from PyPI with

pip install betterbib

Licensing

betterbib checks for a TeX World license on startup. If none is found and you're running interactively, you'll be prompted to enter a license key, start a free trial, or buy a license online.

For non-interactive use (CI, scripts), set the license key via one of the following environment variables:

export TEXWORLD_LIC=<your-license-key>

For commercial licensing, contact texworld@mondaytech.com.

Sync

Simply run

betterbib sync in.bib

to sync your bibliography file with online sources. For example, the input

@article{wiles,
title={Fermat Last Theorem},
doi={10.2307/2118559},
}

is converted to

@article{wiles,
  title     = {Modular Elliptic Curves and Fermat's Last Theorem},
  journal   = {The Annals of Mathematics},
  volume    = {141},
  number    = {3},
  pages     = {443},
  publisher = {JSTOR},
  issn      = {0003-486X},
  url       = {https://doi.org/10.2307/2118559},
  doi       = {10.2307/2118559},
  source    = {Crossref},
}
Usage: betterbib sync [OPTIONS] <INPUT_FILE>

Arguments:
  <INPUT_FILE>  input bibliography file

Options:
      --stdout   Write output to stdout instead of modifying the file in place
      --check    Don't write any changes; report per-entry updates/no-matches and exit with non-zero status if any occurred
  -q, --quiet    Don't show progress info
  -v, --verbose  Print a line per entry showing which source matched, or why it didn't
  -h, --help     Print help

--check is useful in CI: it exits non-zero if any entry would change, without touching the file. Combine with --stdout to inspect the would-be result without writing it.

In --check mode, betterbib also prints one line per entry that needs attention, so you can grep/postprocess the output:

wiles: would update (via Crossref)
unfindable: no match found
in.bib: would update 1 entry
in.bib: 1 entry has no match

no match found means none of the configured sources could resolve the entry (e.g. a DOI that doesn't exist); these entries are not modified either way, but --check still exits non-zero so the case isn't missed silently.

Outside of --check, pass -v/--verbose to get the same kind of detail for an actual (writing) sync run:

$ betterbib sync in.bib --verbose
skipped: skipped (betterbib-skip)
wiles: updated (via Crossref)
unfindable: no match found

--verbose and --quiet are mutually exclusive.

To exclude a single entry from sync (e.g. because you've edited it by hand), add a betterbib-skip field to it:

@article{wiles,
  title          = {Fermat Last Theorem},
  doi            = {10.2307/2118559},
  betterbib-skip = {true},
}

Any value other than false skips the entry; it's left completely untouched (and doesn't count towards --check's change count).

By default, betterbib tries OpenAlex, then the DOI resolver (for entries that already have a DOI), then Crossref, DBLP and PubMed, stopping at the first source that returns a confident, unique match. You can restrict or reorder sources, and tune match confidence, via betterbib.toml:

[sync]
sources = ["crossref", "dblp"]  # default: ["openalex", "doi", "crossref", "dblp", "pubmed"]
minimum-score = 0.0             # minimum match score to accept a result
num-concurrent-requests = 5     # concurrent HTTPS requests
cache-ttl-s = 2592000            # how long API responses are cached (30 days)
timeout-s = 120                  # per-request timeout

Format

betterbib format in.bib

normalizes the cosmetic style of a bibliography file: key case, field alignment, field order, and indentation. It does not change field content (for that, see check --fix).

Usage: betterbib format [OPTIONS] <INPUT_FILE>

Arguments:
  <INPUT_FILE>  File to format

Options:
      --check  Avoid writing any formatted files back; instead, exit with a non-zero status code if any files would have been modified, and zero otherwise
  -h, --help   Print help

Configure the style via betterbib.toml:

[format]
keyword-case = "lower"      # "lower" or "upper"
align-values = true
field-order = "standard"    # "standard", "alphabetical", or "unchanged"
indentation = "  "

Check

betterbib check in.bib

lints a bibliography file for common mistakes. For example:

BIB09 [*] Expected abbreviated given names, got 'Andrew'
 --> in.bib:2:23
  |
1 | @article{wiles,
2 |   author    = {Wiles, Andrew},
  |                       ^^^^^^
3 |   title     = {Modular Elliptic Curves and Fermat's Last Theorem},
  |
help: Replace with `A.`

BIB15 [*] Unprotected word `Fermat`
 --> in.bib:3:44
  |
2 |   author    = {Wiles, Andrew},
3 |   title     = {Modular Elliptic Curves and Fermat's Last Theorem},
  |                                            ^^^^^^
4 |   journal   = {The Annals of Mathematics},
  |
help: Protect with braces: `{Fermat}`

Found 2 errors.
[*] 2 fixable with the `--fix` option.

Pass --fix to apply the auto-fixable ones in place:

Usage: betterbib check [OPTIONS] <INPUT_FILE>

Arguments:
  <INPUT_FILE>  File to check

Options:
      --fix   Apply fixes to resolve lint violations
  -h, --help  Print help
Rule Checks for
BIB01 Fields valid only in BibLaTeX used in a BibTeX file
BIB02 Entry types valid only in BibLaTeX used in a BibTeX file
BIB04 Consecutive whitespace in field values
BIB05 Malformed DOIs
BIB07 Duplicate fields within an entry
BIB08 Duplicate citation keys
BIB09 Given names not matching the configured abbreviation style
BIB10 Journal names not matching the configured abbreviation style
BIB12 Inconsistent location/address style (with/without US state)
BIB13 Incorrectly formatted month field
BIB14 Wrong page-range separator
BIB15 Unprotected capitalized words in titles
BIB16 Missing fields required for the entry type
BIB17 Problematic/non-normalized Unicode
BIB18 Old-style DOI URLs
BIB19 Malformed ISBN/ISSN
BIB22 title/chapter/booktitle/series holding the same text
BIB23 Two-person eponyms (e.g. Cauchy-Riemann) spelled with a hyphen instead of an en dash
BIB24 Unescaped TeX-reserved characters (&, %, #)
BIB25 BibLaTeX pages holding a publisher article number instead of a page range
BIB26 Undecoded XML/HTML entities (e.g. &amp;)

Configure rule behavior, or disable individual rules, via betterbib.toml:

[lint]
journal-abbreviation = "abbreviated"  # "abbreviated" or "full"
given-name-style = "abbreviated"      # "abbreviated" or "full"
page-range-separator = "--"
location-style = "with-state"         # "with-state" or "without-state"
ignore = ["BIB12", "BIB16"]

Convert

betterbib convert in.bib out.ris

converts between BibTeX, BibLaTeX, RIS, and CSL-JSON. The format is inferred from each file's extension; for .bib files specifically, a filename ending in -biblatex (e.g. library-biblatex.bib) is treated as BibLaTeX, anything else as plain BibTeX. This same rule decides the dialect for sync and check as well — it isn't configurable.

Usage: betterbib convert <INPUT_FILE> <OUTPUT_FILE>

Arguments:
  <INPUT_FILE>   input file
  <OUTPUT_FILE>  output file

Options:
  -h, --help  Print help

Dereference DOIs

Given a DOI, generate a bibliography entry for it directly, without an input file:

betterbib doi-to ris 10.1002/andp.19053221004
TY - JOUR
TI - Zur Elektrodynamik Bewegter Körper
JF - Annalen der Physik
VO - 322
IS - 10
SP - 891
EP - 921
PB - Wiley
SN - 0003-3804, 1521-3889
UR - https://doi.org/10.1002/andp.19053221004
DI - 10.1002/andp.19053221004
DS - Crossref
Usage: betterbib doi-to [OPTIONS] <OUTPUT_FORMAT> <DOI>

Arguments:
  <OUTPUT_FORMAT>  output format [possible values: biblatex, bibtex, csl-json, ris]
  <DOI>            doi

Options:
      --source <SOURCE>  Data source [default: crossref] [possible values: crossref, dblp]
  -h, --help             Print help

Cache

sync and doi-to cache online responses locally.

betterbib cache dir    # show the cache directory
betterbib cache clear  # clear the cache

Configuration

betterbib looks for a betterbib.toml file in the current directory or any parent directory. All options shown above ([sync], [format], [lint]) live in this single file; see the snippets above for the available keys and their defaults.

You can also override config for a single file by adding a header comment block starting with // betterbib::

// betterbib: format.keyword-case = "upper"
// sync.sources = ["crossref"]

@article{...}

Metadata

Release files for betterbib 8.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for betterbib 8.0.2
File Actions
betterbib-8.0.2-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for betterbib-8.0.2-py3-none-win_amd64.whl
betterbib-8.0.2-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for betterbib-8.0.2-py3-none-manylinux_2_28_aarch64.whl
betterbib-8.0.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for betterbib-8.0.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
betterbib-8.0.2-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for betterbib-8.0.2-py3-none-macosx_11_0_arm64.whl
betterbib-8.0.2-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for betterbib-8.0.2-py3-none-macosx_10_12_x86_64.whl

Total release size: 26.6 MB

Release files / betterbib-8.0.2-py3-none-win_amd64.whl

Download URL betterbib-8.0.2-py3-none-win_amd64.whl
Size 4.9 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
70fa41aff8f39cce4b58a8af822bed81e614684e1f422cca04c1a749b5329564
BLAKE2b-256 checksum
How to use checksums
765751f09f559ac4a196f32b04a13a9524ee3f8b256a89b6d8aa0652a33ac082
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / betterbib-8.0.2-py3-none-manylinux_2_28_aarch64.whl

Download URL betterbib-8.0.2-py3-none-manylinux_2_28_aarch64.whl
Size 5.7 MB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
06f510f526dd3ae10a113f6ffaf8834352a6828d24010cbbd6dc512c695a2f24
BLAKE2b-256 checksum
How to use checksums
cfaf1bc11e3cee3e15c3e895ffa4cee8e2025033075ac988b4bde8e1322c29c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / betterbib-8.0.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL betterbib-8.0.2-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 5.7 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
6b2067ae7e031f9d4dd6998c9713185d159bf36f4c09dfdd9cdc6c26d65657e8
BLAKE2b-256 checksum
How to use checksums
b6c426ac0d9b1662340208a7d5592c8389745c735c5b3ff1543ec4ce0365275d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / betterbib-8.0.2-py3-none-macosx_11_0_arm64.whl

Download URL betterbib-8.0.2-py3-none-macosx_11_0_arm64.whl
Size 5.0 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
47401411a90290cd8ab16f57b587aaf165fe5395720a83736fcb2b14e72b1ba7
BLAKE2b-256 checksum
How to use checksums
e97ff826dc835c4c64969ae92db2000cef7f090839754cbf54572962af6df5e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / betterbib-8.0.2-py3-none-macosx_10_12_x86_64.whl

Download URL betterbib-8.0.2-py3-none-macosx_10_12_x86_64.whl
Size 5.2 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
8ab13ba35f8e11b029cc669b44526ac17f874e6555bb93e3602463bb44879b4a
BLAKE2b-256 checksum
How to use checksums
6c38b598f7016787d9e4cea2a8cb9dac597203c27059bdc4e7610d079e381092
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for betterbib 8.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for betterbib-8.0.2-py3-none-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page