The space between the number and the unit in “9.81 m/s²” is not there to look tidy. The SI Brochure, issued by the General Conference on Weights and Measures, states that this space is a multiplication sign — which is why a quantity is a single entity that must not be broken at the end of a line — and siunitx is the LaTeX package that takes on this whole family of rules for you. This page follows the three pillars of the current version 3, \num, \unit and \qty, and answers along the way why units are set upright, why digits are grouped with a space rather than a comma, how the S column lines a table up on its decimal marker, and how to translate the \SI and \si you still meet in older posts.
Why not just write \mathrm{kg} by hand
Doing it by hand breaks down because what has to be observed is not a matter of taste but an international standard, and three of its rules bite at once. The first is the typeface. The SI Brochure says that unit symbols “are printed in upright type regardless of the type used in the surrounding text”, because m, kg and s are not variables. But letters in LaTeX math mode are slanted by default, so a bare $9.81 kg$ makes the unit look like the product of an italic k and g. Writing \mathrm{kg} fixes that one spot — and a single paper has several dozen such spots.
The second rule is the space. Section 5.4.3 of the Brochure states that the numerical value always precedes the unit and that a space is always used to separate them — and then explains that this space is regarded as a multiplication sign. So neither 9.81kg nor 9.81 kg is correct. The one exception the standard grants is the degree, minute and second of plane angle (°, ′, ″), which take no space at all. That is why 30.2 °C and 22.20° can sit in the same paragraph: Celsius keeps its space, the angle does not. A document therefore contains both “space before °” and “no space before °”, and keeping that distinction straight by hand across a few hundred occurrences is, frankly, not realistic.
The third is that the pair must not come apart. Since a quantity is the product of a number and a unit, 9.81 must never be left at the end of a line with m/s² starting the next. siunitx forbids that break by default; you switch it on deliberately with allow-quantity-breaks. So if a narrow column reports an underfull hbox, that warning is not a mishap but the rule doing its job. All three concerns are settled by one line in the preamble, \usepackage{siunitx} — with the side benefit that changing one setting afterwards changes the appearance everywhere in the document.
\usepackage{siunitx}
% by hand: three separate things to remember, every time
$9.81\,\mathrm{m}\,\mathrm{s}^{-2}$
% with siunitx: one command, and the standard is applied for you
\qty{9.81}{\metre\per\second\squared}
\qty{100}{\degreeCelsius} % 100 °C - space kept before the degree
\qty{10}{\percent} % 10 % - space here too
\ang{22.20} % 22.20° - but no space for a plane angle\num: what happens to a bare number
\num{…} takes a number on its own and sorts out grouping, exponents, signs and the leading zero according to the standard. \num{12345} gives 12 345, \num{1.234e5} gives 1.234 × 10⁵, and \num{.5} gives 0.5. That last one quietly matters: the SI Brochure requires that “if the number is between +1 and −1, then the decimal marker is always preceded by a zero”, so 0.234 is right and .234 is not. Being able to type .5 in the source and get 0.5 in the output saves more keystrokes than it looks like it should.
Grouping digits with a space rather than a comma is not the package author’s taste. It was fixed by Resolution 7 of the 9th General Conference on Weights and Measures in 1948: numbers may be divided into groups of three to aid reading, and “neither dots nor commas are ever inserted in the spaces between groups”. The same resolution describes the decimal marker as “the comma (French practice) or the dot (British practice)” — a phrasing that reads rather charmingly today. So 43 279.168 29 follows the standard and 43,279.168,29 does not. The default value of siunitx’s group-separator is exactly that thin space, \,.
The input side, by contrast, is forgiving. The default input-decimal-markers is the pair .,, so \num{0,1234} and \num{0.1234} give the same result. The default input-exponent-markers is the four letters dDeE, so even the Fortran-flavoured 3.45d-4 is read as 3.45 × 10⁻⁴. In practice this means numbers pasted straight out of a CSV file or an instrument log can be thrown in without normalising their format first. The one thing \num does not do is multiply: in v3, products of numbers go through the dedicated \numproduct{1.2 x 3.4} (items separated by x). That division of labour also follows the standard, which specifies that when multiplying numbers only the multiplication sign × should be used.
\num{12345} % 12 345 - grouped with a thin space, never a comma
\num{43279.16829} % 43 279.168 29
\num{1.234e5} % 1.234 x 10^5
\num{3.45d-4} % 3.45 x 10^-4 - Fortran-style d also works
\num{0,1234} % 0.1234 - comma accepted on input
\num{.5} % 0.5 - leading zero supplied
\num{-15673} % -15 673
\numproduct{1.2 x 3.4} % 1.2 x 3.4 - products need their own commandDecimal point or decimal comma? locale and output-decimal-marker
Both are correct — that is the standard’s answer. Resolution 10 of the 22nd General Conference on Weights and Measures, in 2003, ruled that the decimal marker “shall be either the point on the line or the comma on the line”, and that the one chosen “should be that which is customary in the language and context concerned”. Setting 9,81 m/s² in a German, French or Spanish document is therefore correct in exactly the same way that 9.81 m/s² is correct in an English one. Neither is the real version and the other an accent. siunitx is honest about this in its design: it keeps the format of the input separate from the format of the output.
There are two ways to switch. For fine control, set the output decimal marker with output-decimal-marker and the digit grouping with group-separator, independently. To switch a whole regional convention at once, use the locale option; the package ships configurations for UK, US, DE (Germany), PL (Poland), FR (France), SI (Slovenia) and ZA (South Africa). The point is that the source never has to change: \qty[locale = DE]{6.789}{\metre} keeps the point in the source and prints 6,789 m. That is what makes it practical to publish one manuscript in an English and a German edition.
For a region that is not shipped — Spanish- or Italian-speaking ones, for instance — locale has nothing to offer, so you write it yourself: \sisetup{output-decimal-marker = {,}}. And there is one trap that is easy to fall into: switching the decimal marker to a comma and then setting the group separator to a comma as well. With both group-separator = {,} and output-decimal-marker = {,} in force, \num{12345.678} prints 12,345,678, and no reader can tell which comma is the decimal marker. That is the moment you understand first-hand why the 1948 resolution went out of its way to say that no dots or commas are ever inserted between groups. Leaving the group separator at its default thin space is the safe choice.
\qty[locale = DE]{6.789}{\metre} % 6,789 m - source keeps the point
\num[output-decimal-marker = {,}]{1.23} % 1,23
\num[group-separator = {,}]{12345} % 12,345 - US/UK habit, not SI
% document-wide, for a locale siunitx does not ship
\sisetup{output-decimal-marker = {,}} % group-separator stays a thin space
% do NOT do this: the output 12,345,678 is unreadable
% \sisetup{output-decimal-marker = {,}, group-separator = {,}}\unit: two ways to write a unit, and what \per does
\unit{…} sets a unit on its own, and there are two ways to write the argument. The literal style types the symbols directly, as in \unit{kg.m/s^2}, where the period . is an inter-unit product, / is a quotient and ^ a superscript. The macro style builds the unit a word at a time out of prefixes, units and powers — \unit{\kilo\gram\metre\per\second\squared} — much as you would read the unit aloud in English. The practical split is clear: use the literal style for a one-off unit written in a hurry, and the macro style when you may later want to change the appearance of every unit at once. Options only get a grip on the macro form.
| Macro | Meaning | Prints |
|---|---|---|
\gram | Base-unit macro; likewise \metre \second \ampere \kelvin \mole \candela | g |
\kilo | A prefix; never valid on its own, a unit must follow | k |
\kilogram | A prefixed unit as one word; same result as \kilo\gram | kg |
\per | Sends the following unit to the denominator: \joule\per\mole | J mol⁻¹ |
\squared | Squares the preceding unit (postfix); \cubed for the cube | m² |
\square | Squares the following unit (prefix); \cubic for the cube | m² |
\degreeCelsius | Degree Celsius; a space is kept before it, as the standard requires | °C |
\percent | Per cent; recognised for use with the SI, and also preceded by a space | % |
How \per looks is decided by the per-mode option — and this is where older tutorials most often get it wrong: the default is a negative power. \unit{\metre\per\second\squared} prints m s⁻², not m/s², and \unit{\kilo\gram\per\cubic\metre} prints kg m⁻³, not kg/m³. For a slash, ask for per-mode = symbol; for a stacked fraction, per-mode = fraction. Write \sisetup{per-mode = symbol} once in the preamble and every unit in the document follows that policy.
When you do choose the slash, siunitx quietly inserts brackets. Section 5.4.6 of the Brochure requires that when dividing with a solidus, parentheses are used to avoid ambiguity: (a/b)/c is acceptable, a/b/c is not. So \unit[per-mode = symbol]{\joule\per\mole\per\kelvin} prints J/(mol K), not J/mol/K. A rule that by hand amounts to “remember to watch the second slash” is instead enforced structurally. The manual adds that in complicated cases negative exponents are to be preferred — which is exactly why per-mode = power is the default.
\unit{kg.m/s^2} % kg m/s^2 - literal input, slash kept
\unit{\kilo\gram\metre\per\second\squared} % kg m s^-2 - default per-mode = power
\unit[per-mode = symbol]{\kilo\gram\per\cubic\metre} % kg/m^3
\unit{\joule\per\mole\per\kelvin} % J mol^-1 K^-1
\unit[per-mode = symbol]{\joule\per\mole\per\kelvin} % J/(mol K) - brackets added
\sisetup{per-mode = symbol} % one policy for the whole document\qty puts number and unit together — ranges, lists and angles
\qty{number}{unit} hands its first argument to \num, its second to \unit, and puts the standard space between them. There is no new notation to learn: whatever you could write for \num and whatever you could write for \unit simply go side by side. The unit part may be a macro form (\metre\per\second\squared) or a literal one (m/s). \qty is the idea from the top of this page — a quantity is the product of a number and a unit — turned directly into a command.
Ranges and lists have their own commands, and the output of \qtyrange{10}{20}{\metre} is the eye-catching one: it prints 10 m to 20 m, not 10–20 m. That, too, comes from the standard. The Brochure warns that physical quantities joined by a dash could be misread as negative values, that writing the values with an en dash and a single unit is likewise incorrect since a quantity is one mathematical entity, and that using the word “to” is strongly recommended. The urge to write 10–20 m in a table heading is strong, and it is against the standard. \qtylist{10;20;30}{\metre} sets 10 m, 20 m and 30 m.
Angles are the one case handled by \ang rather than \qty. As noted above, \ang{45} prints 45° with no space, and passing degrees, minutes and seconds separated by semicolons gives \ang{45;30;15} as 45° 30′ 15″. The first form is the one to reach for by default: the Brochure states that for plane angles it is generally preferable to divide the degree decimally, so 22.20° is preferred over 22° 12′ except in fields such as navigation, cartography, astronomy and the measurement of very small angles. Treat minutes and seconds as a tool for the fields that need them.
\qty{9.81}{\metre\per\second\squared} % 9.81 m s^-2
\qty{1.234e5}{\kilo\gram\per\cubic\metre} % 1.234 x 10^5 kg m^-3
\qty{2.998e8}{m/s} % literal units work here too
\qtyrange{10}{20}{\metre} % 10 m to 20 m - the word "to", not a dash
\qtylist{10;20;30}{\metre} % 10 m, 20 m and 30 m
\ang{22.20} % 22.20° - decimal degrees are preferred
\ang{45;30;15} % 45° 30' 15" - degrees; minutes; secondsUncertainty in brackets: \num{1.234(5)}
Measured values come with an uncertainty. siunitx reads round brackets in the input as exactly that, so \num{1.234(5)} sets 1.234(5). The bracket notation is not a siunitx invention: it is the form the SI Brochure gives in section 5.4.5, where the mass of the neutron is written mₙ = 1.674 927 471(21) × 10⁻²⁷ kg and the figure in parentheses is the standard uncertainty referred to the last digits of the quoted value. Passing (…) to \num is therefore writing the input the way the standard already assumes it will be written.
The presentation is chosen with uncertainty-mode. The default, compact, prints the bracketed figure as digits of the least-significant place (\num{123.45(120)} → 123.45(120)), while full prints the uncertainty as a complete value (→ 123.45(1.20)). Turning on separate-uncertainty gives the \pm form, 1.234 ± 0.005. What deserves attention there is what the unit attaches to: written as 12.3 ± 0.4 kg, the ±0.4 looks as though it carries no unit. siunitx knows this, and \qty[separate-uncertainty]{12.3(4)}{\kilogram} supplies the brackets itself, printing (12.3 ± 0.4) kg.
\num{1.234(5)} % 1.234(5)
\num{123.45(120)} % 123.45(120) - compact, the default
\num[uncertainty-mode = full]{123.45(120)} % 123.45(1.20)
\num[separate-uncertainty]{1.234(5)} % 1.234 +- 0.005
\qty{12.3(4)}{\kilogram} % 12.3(4) kg
\qty[separate-uncertainty]{12.3(4)}{\kilogram} % (12.3 +- 0.4) kg - brackets addedAligning a table on the decimal marker: the S column and table-format
Write S in the column specification in place of c, l or r, and the numbers in that column line up on the decimal marker. Cell contents are read by the same parser as \num, so 1.2e3 becomes 1.2 × 10³ and a comma-written 975,31 becomes 975.31 — a column poured in from a CSV file tidies itself up. This too answers a requirement of the standard: the SI Brochure devotes one short but unambiguous sentence to it, saying that for numbers in a table the format used should not vary within one column.
The first stumble is almost always the column heading. Put text in a cell of an S column and siunitx will try to read it as part of a number, so wrap headings in braces, {Mass} — forget that and the alignment of that one row collapses. The same applies to headings carrying units or footnote marks: protect the whole thing, {Mass / \unit{\gram}}. To steady the width of the column, declare “integer digits.decimal digits” with table-format. S[table-format = 4.1] reserves room for four integer digits and one decimal place in advance, so adding rows later does not shift the column. With uncertainties, write S[table-format = 2.2(1), separate-uncertainty]; with exponents, S[table-format = 1.3e2].
\begin{tabular}{@{}cS[table-format = 4.1]@{}}
\toprule
Entry & {Mass / \unit{\gram}} \\ % braces protect the heading text
\midrule
1 & 1234.5 \\
2 & 12.0 \\
3 & 6.7 \\
\bottomrule
\end{tabular}
% uncertainties and exponents get their own formats
% S[table-format = 2.2(1), separate-uncertainty] -> 12.34 +- 0.05
% S[table-format = 1.3e2]There is a settled convention for putting the unit in the heading as well: not Length [m] but Length / m, dividing by the unit. The reason is a clash of notations — in mathematics [x] means “the dimension of x”. Borrowing square brackets as a container for units makes [a] ambiguous between “the dimension of acceleration” and “the unit is m/s²”. Dividing by the unit leaves the body of the table as pure dimensionless numbers, which dovetails neatly with what the S column does. And when the same alignment is wanted inside \multicolumn or \multirow, use \tablenum[table-format = …]{…}, the macro counterpart of the S column.
The difference between \SI and \qty: moving from v2 to v3
They are the old and the new name for commands that do the same job: \SI is v2, \qty is v3. The author of siunitx, Joseph Wright, rewrote the package internally for v3.0.0, released on 17 May 2021, and revised the document commands to be “more descriptive”. The manual states that \SI, \si, \SIrange and \SIlist remain available but are not recommended for use in new documents; the \qty… family should be used instead. Only \num and \ang kept their names across the change.
| v2 (old name) | v3 (current) | What it does |
|---|---|---|
\SI | \qty{9.81}{\metre\per\second\squared} | Number and unit |
\si | \unit{\kilo\gram} | Unit alone |
\SIrange | \qtyrange{10}{20}{\metre} | A range (10 m to 20 m) |
\SIlist | \qtylist{10;20;30}{\metre} | A list (10 m, 20 m and 30 m) |
\num | \num{1.234e5} (name unchanged) | Number alone |
\ang | \ang{22.20} (name unchanged) | A plane angle |
v3 also tightened the input. The conspicuous case is prefixes: a prefix without a unit is no longer allowed, and \unit{\kilo} stops with ! Package siunitx Error: Found prefix part with no unit. This is not pedantry but alignment with the standard — section 5.2 of the SI Brochure has long said that a prefix is never used in isolation and that compound prefixes are never used. At least part of what looks like a breaking change in v3 is really the package catching up with the rules. In the same spirit, products of numbers moved to \numproduct, products of quantities to \qtyproduct, and complex values to the dedicated \complexnum.
When an old document simply will not compile under v3, the legacy behaviour can be summoned at load time with \usepackage{siunitx}[=v2]. Treat that as life support, though. v3 maps many old option names onto the new ones internally and records a warning in the log each time it does. A document whose log is lined with siunitx warnings is telling you it is time to rename things. If you are starting something new, three commands are enough to learn: \num, \unit and \qty — the number alone, the unit alone, and the two together. Every detail of the standard covered on this page is handled inside those three.
% v2 names: still work, no longer recommended for new documents
\SI{9.81}{\metre\per\second\squared}
\si{\kilo\gram}
% v3 names: use these
\qty{9.81}{\metre\per\second\squared}
\unit{\kilo\gram}
% a prefix on its own is now an error:
% ! Package siunitx Error: Found prefix part with no unit.
\unit{\kilo}
% last resort for a document that will not build with v3
\usepackage{siunitx}[=v2]