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.
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
.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. - With
biblatexthe.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 bybiblatex(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.
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.
- Many
.bststyles have been stable for a long time. - Most
.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).
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.
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.
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.
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).
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/.
As an alternative to manually configuring multiple TeX Live versions on the same machine, you might want to use a Docker image containing the correct TeX Live version. One such image, with some instructions, can be found at https://hub.docker.com/r/makisyu/texlive-2016/.
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.
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 popular online LaTeX editor Overleaf recently added an option to switch between different TeX live versions for compilation of a project. The TeX live 2017 on the Overleaf servers appears to be a pretty good match to the current arXiv system (at least in terms of biblatex and Biber).
In your Overleaf project go to the Menu (on the top left) and select "2017 (Legacy)" under TeX live version. It may be a good idea to clear your project cache after you change the TeX live version. See https://www.overleaf.com/learn/how-to/Clearing_the_cache.
Make sure your project compiles without errors (and ideally without warnings) and that the output looks as desired.
Then press the "Submit" button on the top right and find "arxiv.org". Download the .zip, which contains all required files for the arXiv submission.
See also https://www.overleaf.com/learn/how-to/LaTeX_checklist_for_arXiv_submissions, https://www.overleaf.com/blog/new-feature-select-your-tex-live-compiler-version/ and https://www.overleaf.com/learn/how-to/Using_the_Overleaf_project_menu#TeX_Live_version.
The example project https://www.overleaf.com/read/vcyrqpsrrftx uses TeX live 2017 (if you copy/duplicate this project, it will probably use the newest TeX live version available on Overleaf, so you need to switch back to TeX live 2017 explicitly).
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. Overleaf users can switch between TeX live versions in the menu. As far as biblatex and Biber are concerned the best fit for that task is an un-updated TeX live 2017 installation.