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.

[Splines]

Thanks for your feedback on the approach to update the version. As I don't have any experience in installing LaTeX packages manually (yet), I looked it up when writing our update guide and found this guide for Ubuntu on the official ubuntu.com page, which explained how to do it with .ins files and also used texhash in the user directory. Based on your comments, we should probably ditch that and rewrite the update guide or just advise users to install a current TeX Live distribution directly (on Linux) and manage packages not through any Linux package manager. Glad you're on the LaTeX team and have the know-how ;)

---

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'm not sure I understand this correctly. I'm used to semantic versioning where major, minor or patch versions indicate whether I can update a software without any breaking changes in a backwards compatible manner. So by

So the reason that I don't describe how to update here is I really cannot recommend it.

do you mean users of siunitx shouldn't update to newer versions of your software because for newer versions you might have stepped up expl3 and updating that is non-trivial?

---

(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.)

Unfortunately, I couldn't find any download statistics for Ubuntu packages like texlive-full and the like, but I suspect the number of downloads to be huge. I mean, when I started to learn something about LaTeX at uni, I searched for "install LaTeX" or "LaTeX Ubuntu install" in a search engine. And you'll find a plethora of articles (mainly tailored to users who have probably never opened a console before) explaining how to install LaTeX by just installing the respective apt packages, e.g. this, this, this, this, this and StackOverflow answers like this.

And to be honest, if in 2024 I see a website like the TeX Live website with install instructions in plain HTML as it we were still in the last century, I don't blame anybody if they leave the site very quickly and consider other options where the user guide is more pleasing to the eye and where you only have to do a simple sudo apt install texlive-latex-recommended. This worked fine for me for years until I know want to rely on some more recent versions of the tools like siunitx around LaTeX, so I should definitely look into the "manual" way to install LaTeX directly.

That's all to say that I'm now more uncertain than before with regards to how to set up things for our ResultWizard library (currently in its alpha stage). It allows users to export any variables from Python (including uncertainties and units) and obtain a .tex file with siunitx-specific code in it that they can then use in their LaTeX document. Of course, we'd love to make use of something like

\qty[uncertainty-descriptors={customlabel1,customlabel2}]{1.2 \pm 0.1 \pm 0.05}{\m}

But I'm afraid that for many users this won't work since they have an older version of siunitx installed that does not ship with uncertainty-descriptors yet. So, we will provide a siunitx_fallback flag such that we don't use uncertainty-descriptors and instead do it a bit hacky and manually. Of course, bugs like #725 will occur for them, but there's only so much one can do. At least, things don't look so badly anymore for Ubuntu 24 (e.g. Ubuntu 24.04.1 LTS, codename noble) where sudo apt texlive-science comes shipped with siunitx version 2024-01-25 v3.3.10.

So thanks again for your work on siunitx anyways, it's always a charm to use it in my documents.