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

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.1
File Actions
betterbib-8.0.1-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for betterbib-8.0.1-py3-none-win_amd64.whl
betterbib-8.0.1-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for betterbib-8.0.1-py3-none-manylinux_2_28_aarch64.whl
betterbib-8.0.1-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.1-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
betterbib-8.0.1-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for betterbib-8.0.1-py3-none-macosx_11_0_arm64.whl
betterbib-8.0.1-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for betterbib-8.0.1-py3-none-macosx_10_12_x86_64.whl

Total release size: 26.6 MB

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

Download URL betterbib-8.0.1-py3-none-win_amd64.whl
Size 5.0 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
ab7668dddaea6bcdb5a8958d57a6fef2cea4a5557c05084ff24e78711f3d69ac
BLAKE2b-256 checksum
How to use checksums
3f16c288f02da4608c86b5209615e8ed4b7905f6f02d939d1c307473e569b7d0
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 10, 2026.

Transparency log

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

Download URL betterbib-8.0.1-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
50ada2c05fc17540b7bf08cda12a5bc1603b83a308154f7dd1a546886c6f0361
BLAKE2b-256 checksum
How to use checksums
7c5c8181bf84101eb1f46b6a01a0e4a6cb3281fdec8379a9a0d65401b0c671f3
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 10, 2026.

Transparency log

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

Download URL betterbib-8.0.1-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
4a05d7b2e2dcec2ce579564ebab3ceffb18e8f281606c6f707899ba607b57ab4
BLAKE2b-256 checksum
How to use checksums
dc79d85a5b1750b6cacc82d84aeee939f36eed91c417d4f549616aedf4f8547e
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 10, 2026.

Transparency log

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

Download URL betterbib-8.0.1-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
678232f1e61402e11fc3bcc9a8d43ba43b74272220e4c582e76ed6c400ef4459
BLAKE2b-256 checksum
How to use checksums
bea55ddabc0c0a3c0476a4fbea9aa4433778406993f5a3a9fdcb8a3151f79ab2
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 10, 2026.

Transparency log

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

Download URL betterbib-8.0.1-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
5682eaeb6f57650c72a9659975241bf70e38af1b5ff888cebbc4814cc3c97fe7
BLAKE2b-256 checksum
How to use checksums
382c38ac107bc1522307c4d5caf1ca1cb98b3ac48fdb6b8c478bdf934e528747
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 10, 2026.

Transparency log

Security for betterbib 8.0.1

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.1-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 10, 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