biber / biblatex

Change one word — style=numeric to style=authoryear in the \usepackage line — and every citation in the document, along with every entry in the reference list, comes out in a different shape. That one word is very nearly the whole argument for biblatex and its backend biber. Classic BibTeX locked the formatting inside a .bst program written in a stack language; biblatex hands the formatting back to LaTeX macros you can read and redefine, and leaves the data side — reading, disambiguating, sorting — to biber. This page covers the preamble that makes it work (\usepackage[backend=biber, style=…]{biblatex}, \addbibresource, \printbibliography), the latex → biber → latex → latex build, the citation commands \autocite, \parencite and \textcite, and the single most common accident: an editor that keeps calling bibtex while the bibliography stays empty.

biblatex vs biber: which is the package and which is the program

biblatex is a LaTeX package; biber is an external program. biblatex decides what citations and the reference list look like. biber reads the .bib, resolves cross-references, works out where author names need disambiguating, sorts everything and writes a .bbl. Under BibTeX those two jobs lived together inside one .bst file — both the data processing and the formatting, written in an unnamed postfix stack language, as the BibTeX page describes. biblatex split that layer apart. In the words of its own manual, formatting is now “entirely controlled by TeX macros”, and designing a new style needs nothing but working knowledge of LaTeX.

• parse the .bib (or another data source) into an internal data model
• resolve crossref, entry sets and related entries
• generate the data needed to disambiguate identical names and name lists
• validate each entry structurally against the data model
• sort the reference lists — several lists, in different orders, if asked
• write the .bbl that biblatex then reads back in

The backend is chosen with the backend= option, which takes biber, bibtex or bibtex8; the default is biber. The three differ first of all in character encoding. The biblatex manual describes bibtex as supporting “US-ASCII encoding only. Sorting is always case-insensitive”, bibtex8 as supporting US-ASCII and 8-bit encodings such as Latin 1, and biber as supporting US-ASCII, 8-bit encodings, UTF-8, on-the-fly re-encoding and locale-specific sorting. In other words, choosing bibtex is already a dead end for any non-English bibliography — which is the difference that matters most in practice. biber is written in Perl, but TeX Live and MacTeX ship it as a binary, so no Perl installation is needed.

The names are worth knowing. biblatex was written by Philipp Lehman, who developed it alone from 2006 to 2012. Philip Kime took the package over in 2012, with Moritz Wemheuer contributing regularly from 2017 (Audrey Boruvka and Joseph Wright helped through the handover years). The manual still lists Lehman as an author and states that “much of his excellent original code remains in the core”. biber is the work of Philip Kime and François Charette, and because it was designed for biblatex specifically it cannot be used on its own — hand it a .bst and nothing happens. Where bibtex was a general-purpose tool, biber is a component of biblatex.

The minimum that compiles: \usepackage{biblatex}, \addbibresource, \printbibliography

Three commands do the work. Load the package in the preamble with \usepackage[backend=biber, style=…]{biblatex}, register the database — also in the preamble — with \addbibresource{refs.bib}, and put \printbibliography wherever the list belongs. Citations go through \autocite, \parencite and their relatives. The .bib file itself — entry types such as @article, citation keys, fields — is written exactly as it is for BibTeX and is covered on the bibliography database page. That is precisely why migrating costs less than it looks.

\documentclass{article}
\usepackage[backend=biber, style=authoryear]{biblatex}
\addbibresource{refs.bib}   % preamble only, and the .bib extension IS required

\begin{document}

\textcite{shannon1948} introduced the measure.
Later work built on it \autocite[see][45]{knuth1984}.

\printbibliography

\end{document}

The first thing that trips up arrivals from BibTeX is how the database is registered. \addbibresource is preamble-only and replaces \bibliography{refs} at the end of the body. And you must write the .bib extension: \bibliography took none, but \addbibresource demands the full file name, so \addbibresource{refs} simply fails to find the file. Write it several times to split the database across files; with biber as the backend it also accepts glob patterns such as \addbibresource[glob]{bib/*.bib} and remote resources beginning with http://. Note that \bibliographystyle has no role here — the style is decided by the \usepackage options instead.

That style= is in fact a master option that loads two files at once: style=authoryear pulls in authoryear.bbx for the reference list and authoryear.cbx for the citations. The default is numeric. Only when the two must diverge — say, an author–year list with numeric citations — do you set bibstyle= and citestyle= separately. Day to day, the single style= is enough.

Why the build runs latex → biber → latex → latex

Because LaTeX does not know what it cited until it has run once. On the first pass biblatex writes the citation keys and the entire configuration into an XML control file, the .bcf. biber reads that .bcf, matches it against the .bib, processes everything and writes a .bbl. The second pass pulls the .bbl in; the third settles the cross-references and page numbers. The arithmetic is the same as BibTeX’s, but the program you call is biber, not bibtex, and what you hand it is not the .tex but the job name without an extension. With pdflatex or lualatex only the latex step changes name; the structure is identical.

$ pdflatex document.tex   # 1st pass: writes document.bcf with the cited keys
$ biber    document       # NOT bibtex, and no .tex extension: reads .bcf, writes .bbl
$ pdflatex document.tex   # 2nd pass: pulls the .bbl in
$ pdflatex document.tex   # 3rd pass: settles cross-references and page numbers

Almost every failure here has the same cause: the editor or latexmk is still configured to call bibtex. biblatex writes no \citation, no \bibdata and no \bibstyle into the .aux at all, so running bibtex document produces three lines together: I found no \citation commands---while reading file document.aux, I found no \bibdata command---while reading file document.aux, I found no \bibstyle command---while reading file document.aux. No .bbl is produced, and LaTeX responds with LaTeX Warning: Empty bibliography plus LaTeX Warning: Citation 'knuth1984' on page 1 undefined, followed by Package biblatex Warning: Please (re)run Biber on the file:. That last line is the answer in full — run biber where you were running bibtex.

$ latexmk -pdf document.tex   # detects biblatex in the .fls/.bcf and runs biber itself

Typing four commands by hand is not a workflow, so in practice latexmk handles it. Recent versions detect biblatex and call biber automatically, repeating the passes as often as needed. From an editor, the safest route is a latexmk-based engine: the LaTeXmk engines in TeXShop, or a latexmk recipe in VS Code’s LaTeX Workshop. Overleaf detects biblatex and runs biber on its own. Only hand-rolled build scripts need attention — change the bibtex line to biber.

is wrong format version: biber and biblatex ship as a matched pair

biber and biblatex only work in matching versions. The biber manual carries a compatibility table for the two, and from biber 2.7 / biblatex 3.7 onward the minor numbers advance in lock step — TeX Live 2024 ships biber 2.19 with biblatex 3.19. This bites when a package manager updates biblatex alone, or when a separately installed biber (from Homebrew, say) sits earlier in the PATH. The symptom is the warning Package biblatex Warning: File 'document.bbl' is wrong format version - expected … together with a bibliography that refuses to change. The cure is dull: update biber and biblatex together from the same distribution, delete document.bbl, and rebuild. Comparing biber --version with the biblatex version printed at the top of the log tells you immediately whether they have drifted apart.

style=numeric vs style=authoryear: switching citation style with one word

Write a different name in style= and the citations and the reference list change together. biblatex ships five general-purpose families — numeric, alphabetic, authoryear, authortitle and verbose — each with variants. The interesting part is that a style also sets its own default for autocite= at load time: numeric, alphabetic and authoryear set autocite=inline, while authortitle and verbose set autocite=footnote. The assumption about the discipline — citations in the running text, or sources dropped into footnotes — is baked into the style itself.

When a venue prescribes a format, the fastest route is a ready-made style package. TeX Live carries biblatex-ieee for engineering, biblatex-apa for psychology and its neighbours, biblatex-chicago and biblatex-mla for the humanities, biblatex-nature and biblatex-science for the natural sciences, oscola for English law, and a row of national standards: biblatex-gb7714-2015 for the Chinese GB/T 7714-2015, biblatex-gost for the Russian GOST, biblatex-abnt for the Brazilian ABNT, biblatex-dw for German humanities. Where a journal still hands out a .bst and nothing else, staying on BibTeX remains the honest answer; the BibTeX page sets out where that line falls.

\autocite vs \parencite vs \textcite: which citation command to use

Use \textcite when the author’s name is read as part of the sentence, \parencite when the citation sits outside it as a note, and \autocite when you want the style to decide. The grammatical reason for that three-way choice — that “Knuth (1986) showed” and “…as has been shown (Knuth, 1986)” are different grammatical objects — is set out on the citing basics page; here we look at the machinery. Every citation command takes the form \parencite[prenote][postnote]{key} and accepts several comma-separated keys. One bracket gives a postnote — \parencite[45]{knuth1984} — and two give both — \parencite[see][45]{knuth1984}.

\autocite sits one level above the others: what it actually becomes is decided by the autocite= option on \usepackage. The values are plain (behaves like \cite), inline (\parencite), footnote (\footcite) and superscript. And \autocite does not merely look ahead at punctuation — it moves it. With autocite=footnote, a trailing punctuation mark is shifted so that the footnote mark prints after the punctuation. That small courtesy is what lets you flip an entire document from in-text citations to footnote citations without going back to repunctuate every sentence.

To cite several works at once, each with its own postnote, there are multicite forms ending in s. \parencites[35]{key1}[88--120]{key2}{key3} keeps a single pair of parentheses while giving each work its own page range; \autocites and \footcites follow the same pattern. And if your fingers still know natbib from the BibTeX years, \usepackage[natbib=true]{biblatex} makes \citep, \citet and friends available as aliases. It is a useful bridge during migration, though new documents behave more predictably under a style change if they stay with biblatex’s own commands.

sorting= and sortlocale=: getting a non-English bibliography in the right order

The order is set by sorting=. The default is nty — the initials of name, title, year. Others include nyt (name, year, title), ynt (year, name, title), ydnt (year descending) and none, which leaves entries in citation order. All of them switch without touching the .bib. Under BibTeX these choices were buried inside the .bst, reachable only by picking between plain, unsrt and alpha.

On top of that, “the right order” for the same strings differs by language. biber delegates this to the Perl module Unicode::Collate, which implements the full Unicode Collation Algorithm (UCA), and then layers CLDR locale tailoring on top. The effect is easy to see. In German, sortlocale=de_DE gives Mohr → Möller → Muster; switch to the phone-book ordering with sortlocale=de_DE_phonebook and ö is treated as oe, so the list becomes Möller → Mohr → Muster. Spanish is more dramatic: with traditional orthography, sortlocale=es_ES_trad treats ch as a letter of its own, so Chávez sorts after Cortázar (under the modern es_ES it is Cela → Chávez → Cortázar). The biber manual flags this explicitly — babel’s spanish maps to the modern es_ES, so if you want the traditional order you have to name es_ES_trad yourself.

\usepackage[
  backend=biber,
  style=authoryear,
  sorting=nyt,                % name, year, title
  sortlocale=de_DE_phonebook, % locale tailoring: umlauts sort as oe/ue/ae
  maxbibnames=99,             % list every author in the bibliography
  maxcitenames=2,             % but shorten to "et al." inside citations
  backref=true                % back-links from each entry to its citations
]{biblatex}

A collation algorithm can only work with the characters it is handed, and that limit bites in Japanese, Chinese and Korean. sortlocale=ja_JP does apply the Japanese tailoring, but kanji carry no reading, so expecting gojūon or pinyin order will disappoint. If the order must follow the reading, the reading has to be in the data: put a name’s reading in sortname, or an arbitrary sort key in sortkey. The biblatex manual calls sortkey the master sort key — when it is present, biblatex sorts by it and ignores everything else except presort. For the one entry that refuses to fall into line, that is the last resort that always works.

The same \usepackage line also governs how author lists are truncated. maxnames defaults to 3 and minnames to 1; maxbibnames and maxcitenames simply inherit maxnames unless given. So maxnames is the parent and the other two are its children. The combination people actually reach for is the one in the code above: list every author in the bibliography (maxbibnames=99) while cutting citations down to two names plus “et al.” (maxcitenames=2) — something maxnames alone cannot express. Add backref=true and each entry ends with the pages on which it was cited, which earns its keep when proofreading a long manuscript.

Splitting the bibliography: \printbibliography[type=…] and keyword=

\printbibliography may appear as often as you like, with a different filter each time. The keys are type= (only that entry type), nottype= (all but that type), keyword= and notkeyword= (filtering on the keywords field in the .bib), category= and notcategory= (classes declared with \DeclareBibliographyCategory), plus heading= and title= for the headings. Separating primary from secondary sources, or books from articles, therefore costs no change to the data at all. For anything more intricate, \defbibfilter defines a filter of your own — and that is also the tool for splitting a list by language, since the langid field only switches localisation and hyphenation and does not divide anything by itself.

\printbibliography[type=article,   title={Journal articles}]
\printbibliography[type=book,      title={Books}]
\printbibliography[keyword=primary, title={Primary sources}]
\printbibliography[nottype=misc,   heading=bibintoc, title={Everything else}]

The decision comes down to two steps. If the venue hands you a .bst, stay with BibTeX; if the format is yours to choose, move to biblatex and biber. After the move there are only three things to do: put \usepackage[backend=biber, style=…]{biblatex} and \addbibresource{refs.bib} in the preamble, place \printbibliography, and call biber in place of bibtex — or let latexmk do it. The .bib file is common to both, so nothing you have accumulated is lost. What has changed, after forty years, is that altering the format is no longer a matter of rewriting a .bst but of changing one word in \usepackage.