Bibliography files are notoriously hard to work with. betterbib is a fast, single-binary command-line tool that helps:
-
betterbib syncenriches your bibliography entries with data from online sources, e.g., -
betterbib formatnormalizes the cosmetic style of your bibliography files (key case, value alignment, field order, indentation). -
betterbib checklints bibliography files for common mistakes (malformed DOIs, duplicate keys, missing fields, inconsistent name/journal abbreviations, ...) and can auto-fix most of them. -
betterbib convertconverts between bibliography formats, e.g. -
betterbib doi-toturns a DOI into a bibliography entry.
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. &) |
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)
| File | Actions Reset | |||
|---|---|---|---|---|
| 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 logRelease 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 logRelease 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.