biblatex and the arXiv
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.
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.
.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
- 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
.bblfile into your
.texdocument and the formatted bibliography will appear where the code has been pasted. The output formatting is done by BibTeX following the instructions of a
.bstbibliography style (
\bibliographystyle). The LaTeX commands used in the
.bblfile are usually fairly high-level.
.bblfile contains only the relevant raw entry data in a format that is easier to parse for LaTeX than
.bibfiles (it also contains additional meta-information generated by Biber that was not present in the
.bibfile, 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
.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.
.bststyles have been stable for a long time.
.bststyles use fairly high-level macros that are unlikely to have undergone change (there are some counter examples here: some old
.bststyles 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).
.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
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.
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
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.
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.