Upgrade guide for versions prior to 3.1.11 (2022-12-05) to a more recent version

[Splines]

In our python library ResultWizard, we give users the following advice on how to upgrade to a newer version of siunitx. The problem is that if you installed siunitx via sudo apt install texlive-science, it will be an outdated version. Here's our current upgrade guide:

siunitx upgrade guide

In version v3.1.0 (2022-04-25), siunitx introduced "support for multiple uncertainty values in both short and long form input". We make use of this feature in ResultWizard when you specify multiple uncertainties for a result.

Unfortunately, it may be the case that you're using an older version of siunitx that doesn't ship with this feature yet. Especially if you've installed LaTeX via a package manager (e.g. you installed siunitx via sudo apt install texlive-science). To determine your siunitx version, include the following line in your LaTeX document:

\listfiles % add this before \begin{document}, i.e. in your LaTeX preamble

Then, compile your document and check the log for the version of siunitx.

If it's older than v3.1.0 (2022-04-25), don't despair. You can upgrade as follows:

---

How the update process works depends on your LaTeX distribution and how you installed it. E.g. you might be using TeX Live on Ubuntu and installed packages via apt, e.g. sudo apt install texlive-science (which includes the LaTeX siunitx). These pre-built packages are often outdated, e.g. for Ubuntu 22.04 LTS (jammy), the siunitx version that comes with the texlive-science package is 3.0.4. Therefore, you might have to update siunitx manually. See an overview on how to install individual LaTeX packages on Linux here.

A quick solution might be to simply install a new version of siunitx manually to your system. There's a great and short Ubuntu guide on how to install LaTeX packages manually here. The following commands are based on this guide. We will download the version 3.1.11 (2022-12-05) from GitHub (this is the last version before 3.2 where things might get more complicated to install) and install it locally. Don't be scared, do it one step at a time and use the power of GPTs and search engines in case you're stuck. Execute the following commands in your terminal:

# Install "unzip", a tool to extract zip files
sudo apt install unzip

# Download v3.1.11 of siunitx from GitHub
curl -L https://github.com/josephwright/siunitx/releases/download/v3.1.11/siunitx-ctan.zip > siunitx-ctan-3.1.11.zip

# Unzip the file
unzip ./siunitx-ctan-3.1.11.zip
cd siunitx/

# Run LaTeX on the .ins file to generate a usable .sty file
# (LaTeX needs the .sty file to know what to do with the \usepackage{siunitx}
# command in your LaTeX preamble.)
latex siunitx.ins

# Create a new directory in your home directory
# to store the new package .sty file
mkdir -p ~/texmf/tex/latex/siunitx  # use any location you want, but this one is common
cp siunitx.sty ~/texmf/tex/latex/siunitx/

# Make LaTeX recognize the new package by pointing it to the new directory
texhash ~/texmf/

🙌 Done. Try to recompile your LaTeX document again. You should see version v3.1.11 of siunitx in the log file. And it should build. Don't forget to remove the \listfiles from your LaTeX document to avoid cluttering your log file (which is ironic for LaTeX, we know).

In case you don't wan't the new siunitx version anymore, just run the following command to remove the .sty file. LaTeX will then use the version of siunitx it finds somewhere else in your system (which is probably the outdated one you had before).

rm ~/texmf/tex/latex/siunitx/siunitx.sty

---

Unfortunately, this is only working fine up to version 3.1.11 (2022-12-05). In v3.2.0 - 2023-01-03, a version of expl3 - 2022-11-09 or later is required. Efforts to manually update expl3 (with a procedure similar to the one described in our guide) failed, see this error. Related issues might be this and this.

Of course, one could argue: "Why don't you update your entire LaTeX distribution to a newer version and use tlmgr, then you wouldn't have to deal with issues like this"? While that might be true, we want to acknowledge the reality where many people will only install LaTeX and packages via the apt package manager (me included). It's just very convenient if you want to get things done. This answer might be very helpful to find out different ways to install LaTeX.

So, what we're looking for is a hopefully "easy" way for users to upgrade to a more recent version of siunitx without having to revamp their whole LaTeX setup. This is what our "upgrade guide" intended to do by compiling and installing a .sty file just for siunitx on their system -- which unfortunately only works up to 3.1.11 (2022-12-05).

[josephwright]

So, what we're looking for is a hopefully "easy" way for users to upgrade to a more recent version of siunitx without having to revamp their whole LaTeX setup. This is what our "upgrade guide" intended to do by compiling and installing a .sty file just for siunitx on their system -- which unfortunately only works up to 3.1.11 (2022-12-05).

Upgrading expl3 is nowadays on the same level as upgrading the LaTeX kernel: non-trivial. It requires re-building format files, which is not something I can recommend to end users to do manually. (As a member of the LaTeX team, it is something I do but that's a very special case.)

Even without that particular issue, manually updating packages used by many others is always risky: try it with something like hyperref or babel, for example. So the reason that I don't describe how to update here is I really cannot recommend it. (I know it's hard to be sure, but I suspect 'most' users are either using vanilla TL/MiKTeX or using Overleaf, so don't face the question of a Linux package-managed install at all.)

[josephwright]

Not directly related, but some comments on

# Install "unzip", a tool to extract zip files
sudo apt install unzip

# Download v3.1.11 of siunitx from GitHub
curl -L https://github.com/josephwright/siunitx/releases/download/v3.1.11/siunitx-ctan.zip > siunitx-ctan-3.1.11.zip

# Unzip the file
unzip ./siunitx-ctan-3.1.11.zip
cd siunitx/

# Run LaTeX on the .ins file to generate a usable .sty file
# (LaTeX needs the .sty file to know what to do with the \usepackage{siunitx}
# command in your LaTeX preamble.)
latex siunitx.ins

# Create a new directory in your home directory
# to store the new package .sty file
mkdir -p ~/texmf/tex/latex/siunitx  # use any location you want, but this one is common
cp siunitx.sty ~/texmf/tex/latex/siunitx/

# Make LaTeX recognize the new package by pointing it to the new directory
texhash ~/texmf/

There are a few oddities here plus one really rather questionable thing. I'm not sure why you ask people to download using curl rather than the web interface, but like most LaTeX packages, end users should be accessing CTAN not GitHub. There, they'll find a TDS-style zip ready to install: almost no-one is unpacking .ins files manually nowadays. You've also missed out everything except siunitx.sty: there are other files unpacked. The bit I would really encourage you to change is running texhash on the personal tree. Normally, this tree is not hashed, meaning that TeX simply searches it during each run. That's a good balance as there are typically only a small number of files here and it means users don't have to remember to hash every time. Once there is a hash file, that no longer happens: it's hash or nothing.

[josephwright]

So, what we're looking for is a hopefully "easy" way for users to upgrade to a more recent version of siunitx without having to revamp their whole LaTeX setup. This is what our "upgrade guide" intended to do by compiling and installing a .sty file just for siunitx on their system -- which unfortunately only works up to 3.1.11 (2022-12-05).

Upgrading expl3 is nowadays on the same level as upgrading the LaTeX kernel: non-trivial. It requires re-building format files, which is not something I can recommend to end users to do manually. (As a member of the LaTeX team, it is something I do but that's a very special case.)

Note that for this reason I don't step the requirements very often: mainly when there is a deprecation in expl3.

[Skillmon]

Wouldn't it be easier to clone a specific commit (the one tagged v3.1.11) and run l3build install instead of manually rescript that.