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.
Install betterbib from PyPI with
pip install betterbibbetterbib 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.
Simply run
betterbib sync in.bibto 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 timeoutbetterbib format in.bibnormalizes 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 = " "betterbib check in.biblints 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"]betterbib convert in.bib out.risconverts 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
Given a DOI, generate a bibliography entry for it directly, without an input file:
betterbib doi-to ris 10.1002/andp.19053221004TY - 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
sync and doi-to cache online responses locally.
betterbib cache dir # show the cache directory
betterbib cache clear # clear the cachebetterbib 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{...}