Skip to content

biblatex and the arXiv

Kartik Singhal edited this page Oct 30, 2019 · 17 revisions

This page contains a short explanation and a possible solution for the dreaded

Package biblatex Warning: File '<file>.bbl' is wrong format version - expected 2.8.

error that many people will have met upon submitting a .bbl file for biblatex to the arXiv (https://arxiv.org/).

The first sections explains what this error means and why it appears, the second section deals with ways to obtain suitable package versions and the last section explains which TeX live installation is suitable for the task.

If you are having trouble submitting your biblatex-generated bibliographies to the arXiv, please make sure you have read the entire guide. Throughout this guide many questions and answers on TeX Stackexchange are linked, if open questions remain even after you have read this guide, you may want to consult the links as well.

.bbl files

What does the .bbl file do?

When you create a bibliography in your LaTeX document LaTeX does not read the bibliographic data from the .bib file itself, instead you need to run an auxiliary program (BibTeX or Biber) to compile the bibliography into a format usable by LaTeX. The whole process is explained brilliantly by Paul Stanley in https://tex.stackexchange.com/a/63875/133551 – if you are not familiar with the compilation cycle of running LaTeX, Biber/BibTeX, LaTeX, LaTeX or the reasons why that order is necessary, please have a look at that explanation.

The .bbl file as produced by BibTeX or Biber contains the relevant data from the .bib file in a format that LaTeX can understand and use. The format of the .bbl file differs significantly between classical BibTeX and biblatex.

  • With classical BibTeX that file contains a fully formatted bibliography environment that can be typeset directly by LaTeX. In fact you can paste the contents of the .bbl file into your .tex document and the formatted bibliography will appear where the code has been pasted. The output formatting is done by BibTeX following the instructions of a .bst bibliography style (\bibliographystyle). The LaTeX commands used in the .bbl file are usually fairly high-level.
  • With biblatex the .bbl file contains only the relevant raw entry data in a format that is easier to parse for LaTeX than .bib files (it also contains additional meta-information generated by Biber that was not present in the .bib file, furthermore the entries are already sorted). The data still has to be processed by biblatex (as a LaTeX package) before it can be typeset. All the output formatting happens on the LaTeX side.

In both cases the .bbl file is a temporary and intermediate file to pass information from the .bib file to LaTeX, but with BibTeX that file contains typesettable material, while with biblatex the file contains data that needs to be processed further before it can be typeset.

.bbl file versions

BibTeX's .bbl files don't usually know a .bbl file version, a .bbl file produced years ago by an older version of a style usually works fine now. This has two main reasons.

  1. Many .bst styles have been stable for a long time.
  2. Most .bst styles use fairly high-level macros that are unlikely to have undergone change (there are some counter examples here: some old .bst styles still use the deprecated two-letter font switches (https://texfaq.org/FAQ-2letterfontcmd), with a modern KOMA script version those font switches are disabled by default and need to be requested with a compatibility option).

biblatex's .bbl files on the other hand have a .bbl file version. Since the .bbl files is used to pass information from the .bib file to biblatex it is crucial that biblatex understand the format of the .bbl file.

Sometimes development of new features for biblatex necessitates changes in the information or the format of the information passed by Biber to biblatex. Since the .bbl file is temporary in nature (it is recreated by a Biber run, which is necessary whenever information in the .bib file changes) it is usually seen as acceptable to implement changes that make the format of the .bbl backwards incompatible. In that case the .bbl file version is increased and biblatex will only accept .bbl files with the correct version number. Likewise Biber will only produce .bbl files of a particular .bbl file version. See also https://tex.stackexchange.com/q/410512/.

Please note that the .bbl file version does not coincide with the biblatex version. It is not unusual for several biblatex versions to accept the same .bbl file version, for example biblatex 3.5, 3.6 and 3.7 all work with .bbl file version 2.8.

As a final note: While this section was written with biblatex and the Biber backend in mind much the same holds for the BibTeX backend for biblatex as well. A BibTeX-produced .bbl file for biblatex must have been processed with the correct biblatex version (specifically the correct version of biblatex.bst), otherwise a similar error occurs.

.bbl files in arXiv uploads

The arXiv does not want to have to go through a full cycle of running LaTeX, Biber/BibTeX, LaTeX, LaTeX on your .tex file and does not want you to upload your .bib file. Instead you are asked to upload the .bbl file produced by BibTeX or Biber, this cuts down the number of required compilation steps on the arXiv side.

If you upload a .bbl file for biblatex, the version of the .bbl file you upload must coincide with the version that the biblatex installed on the arXiv system expects.

At the moment the arXiv runs biblatex 3.7, which expects .bbl file version 2.8. That means that the .bbl file you upload should be produced by biblatex 3.7 and Biber 2.7 (biblatex 3.5 or 3.6 with Biber 2.6 would also be OK). So the only way to satisfy the arXiv is to obtain those biblatex and Biber versions and run your document with them.

Possible solutions

There are two major approaches: either upload the relevant parts of your local version of biblatex to the arXiv as part of your paper submission (so that your local .bbl works), or install a compatible version of biblatex locally. The former allows you to use newer biblatex features, but you might run into incompatibilites with other packages, while the latter might be "safer" but requires you to install (and use) old versions of packages locally.

Uploading the relevant parts of biblatex

You'll need to include not only biblatex.sty but also the relevant bbx and cbx files, and so on. Luckily, latexmk will tell you which files are needed (with the -deps flag). This Python script by Dougal Sutherland attempts to make a .tar.gz containing your sources as well the needed parts of biblatex (and any other packages you want to include) that you can upload to the arXiv.

Getting the right package versions

Older release versions of both biblatex and Biber are available on Sourceforge (https://sourceforge.net/projects/biblatex/files/ and https://sourceforge.net/projects/biblatex-biber/files/biblatex-biber/). The sources are on GitHub (https://github.com/plk/biblatex/ and https://github.com/plk/biber), please note that these sources are not ready for a drag-and-drop install. Biber must be built first and even the biblatex sources must undergo a short install process, see the respective 'readme' files in the repositories for more information.

It is not recommended to replace only your current biblatex and Biber installation with older versions. biblatex depends on several packages and biblatex styles may have version dependencies as well. That means that you can never be sure that only biblatex and Biber need to be replaced. Other packages and styles may need to be replaced as well. Historic versions of dependencies may not be publicly available (CTAN only has the current versions), so it can be extremely hard to set up a fully functioning system that way. See also https://tex.stackexchange.com/q/438449/. Instead it is recommended to obtain a complete system with the correct biblatex and Biber versions.

The safest and least work-intensive way to obtain a full system with the correct versions would be to install a TeX Live that comes closest to the overall package requirements (and possibly update or downgrade certain [very few] packages).

Installing TeX Live

TeX Live is one of the major TeX distributions in use today. Each year around April a new version of TeX Live is released. These releases update the TeX binaries as well as all installed packages. During the year (with the exception of a freeze period before a new TeX live release) packages can be updated from CTAN via tlmgr. See https://tex.stackexchange.com/q/107017/.

Historic TeX Live releases are available at ftp://tug.org/texlive/historic/. The distributions are in the state TeX Live was released that year and do not include any updates. Historic releases also have no way of getting updates for certain packages.

You can install several versions of TeX Live on the same machine and maintain and use them separately. This is easily done by setting the PATH variable in a way to prefer the binaries from one of the installed TeX Live versions; see https://tex.stackexchange.com/q/150892/ and https://tex.stackexchange.com/q/6521/. MacTeX even includes a handy utility to switch between the versions without having to change the PATH manually. See http://www.tug.org/mactex/multipletexdistributions.html and https://tex.stackexchange.com/q/7295/.

TeX Live on arXiv

Stability and maintainability is an important requirement for the arXiv so it is not viable to deploy rolling package updates and yearly TeX Live updates on their system. Currently (September 2018) the arXiv is running TeX Live 2016, but they did not install that version on their servers immediately when it came out in spring 2016, the deployment was completed in February 2017. It stands to reason that the package versions installed on the arXiv date to around winter 2016/17. See https://confluence.cornell.edu/display/arxivpub/2016+arXiv+Roadmap, https://tex.stackexchange.com/q/358831/.

Since the TeX Live 2016 on the arXiv includes updates made to packages during 2016, the historic TeX Live 2016 may not accurately reproduce the version on the arXiv. (For example TeX Live 2016 would include biblatex 3.3, but the arXiv runs at least 3.5.) Indeed as far as biblatex and Biber are concerned TeX Live 2017 would be a better fit for the arXiv system (as it is today). See also https://tex.stackexchange.com/q/429436/ and https://tex.stackexchange.com/q/450933/.

For future reference it might be a good idea to track the development of the TeX versions on the arXiv and take a snapshot of a current system when arXiv announce a new TeX Live version has been deployed.

Installing historic TeX Live versions

As mentioned above, images of historic TeX live releases are kept at ftp://tug.org/texlive/historic/. Download the ISO of the version you would like to install, mount it and follow the installation procedure. After the installation is finished you should have a fully working TeX live installation on your system. You can use it either by setting up the PATH as necessary or (more awkwardly) by calling the binaries with full path names.

tl;dr

The error message means that the version of biblatex and Biber that produced the .bbl file you uploaded is not the same as the version of biblatex that the arXiv is running. Note that the .bbl format version (2.8) reported in the error message does in general not coincide with either the biblatex or the Biber version.

You can either upload your version of biblatex, or make a compatible .bbl to the arXiv's version by installing a matching system locally. Currently the arXiv runs biblatex 3.7, so you should upload a .bbl file that was produced with and for biblatex 3.7 and Biber 2.7. Instead of downgrading only certain packages, it can be easier to install a complete TeX distribution that tries to mirror the package version on the arXiv. As far as biblatex and Biber are concerned the best fit for that task is an un-updated TeX live 2017 installation.

You can’t perform that action at this time.