Moving from siunitx v2 to v3

With v3 of siunitx out, I am as expected getting quite a few questions about moving from v2. In the main, this is quite easy as there is a decent amount of compatibility code. Here, I’ll pick out a few cases where you might want some adjustments.

Working with Overleaf

One thing that people sometimes need is to work with the latest version but allow their input to work with the older version: that’s particularly true if you work with people using Overleaf, as it will be some time before they update to v3. You can of course just stick to the v2 interfaces, but if you’d prefer to have v3 if possible, then you will need to define \qty and \unit (and maybe others) conditionally. I’d recommend doing that using

\usepackage{siunitx}
\ifdefined\qty\else
  \ifdefined\NewCommandCopy
    \NewCommandCopy\qty\SI
  \else
    \NewDocumentCommand\qty{O{}mm}{\SI[#1]{#2}{#3}}
  \fi
\fi
\ifdefined\unit\else
  \ifdefined\NewCommandCopy
    \NewCommandCopy\unit\si
  \else
    \NewDocumentCommand\unit{O{}m}{\si[#1]{#2}}
  \fi
\fi

That then leaves options, but almost always these should be set in the preamble, so are a ‘one shot’. You can of course add to my tests above to know which version is in use, and set selectively.

Working with products or complex values

For people who’ve been using products or complex numbers in \SI in v2, one could use a similar approach to the above to ‘keep’ the functionality by setting it equivalent to the new \qtyproduct or \complexqty commands: of course, if you want both then you’ve got to make bigger changes. For example, to retain the ability to use products in \SI, you’d use

\usepackage{siunitx}
\ifdefined\qtyproduct\else
  \ifdefined\DeclareCommandCopy
    \DeclareCommandCopy\SI\qtyproduct
  \else
    \DeclareDocumentCommand\SI{O{}mm}{\qtyproduct[#1]{#2}{#3}}
  \fi
\fi

at the cost that the code is a bit slower than \qty for input without products. Complex values would be handed the same way, just changing the command you use as a ‘replacement’.

Using litres (liters)

In v2, \litre and \liter produced different output: that was not the best interface decision. So in v3 they are the same, but that means of course that you might see a change. Luckily, you can set the output you want and get the same in both v2 and v3.

\DeclareSIUnit\litre{l}