# biblatex and the arXiv

``````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.

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.

##### Clone this wiki locally
You can’t perform that action at this time.