Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
siunitx is a LaTeX package for formatting numbers, units and physical quantities consistently, including decimal-aligned table columns. Use its number and quantity commands for manuscript values, then set rounding and table layout separately: the space reserved for a number does not determine its scientific precision.
The workflow below builds a small quantity example and a numeric table, then checks what each formatting control actually changed. The downloadable data table after the article maps these checks to the relevant documentation. It complements the SI units in scientific writing guide, which explains notation conventions rather than package syntax.
What it is used for in research
Joseph Wright’s siunitx package separates numerical and unit input from its printed appearance. The maintainer’s documentation describes automated number processing, unit formatting and tabular alignment, with options for different typographic conventions. That makes it useful when the same quantities appear in manuscript paragraphs, equations and results tables: authors can express the input consistently while controlling how it is printed.
Three commands establish the basic distinction. \num{12345.678} formats a number without a unit. \unit{\milli\metre} formats a unit without a number. \qty{12.345}{\milli\metre} combines them into a quantity. Keeping these roles separate makes it easier to inspect a table heading independently of its data cells, or to change unit presentation without rewriting every measurement.
The package also provides lists, ranges, angles and numeric table columns. Its manual explains that macro-based unit input can change appearance through options while retaining the same source expression. This is a typesetting capability: selecting a display option is a different decision from establishing how a measurement was obtained or how many digits its uncertainty supports. The examples here demonstrate syntax and presentation, with no claim about experimental results.
Install or access
Obtain siunitx through the official CTAN package entry or the package manager supplied with your TeX distribution. CTAN lists it in both TeX Live and MiKTeX. The manual’s installation section says most users will not need a separate manual installation because current distributions make it available through their package management systems.
Load the package in the document preamble with \usepackage{siunitx}. This goes before \begin{document}, alongside the document’s other package declarations. The command makes the number, quantity and S-column interfaces available to the document. Start with the small document below before transferring its working commands into a journal template.
For a manual installation, the documentation identifies the pre-extracted siunitx.tds.zip archive on CTAN and describes extracting it into a local texmf directory. Prefer your distribution’s package management instructions when managing a distribution installation; the manual route is a separate documented option. Avoid copying an isolated example from an older package release and assuming all of its option names remain the recommended ones.
The version 3 manual retains the older \SI and \si interfaces for compatibility but recommends \qty and \unit for new documents. A collaborator’s older source file may therefore use different names for the same general task. In a shared manuscript, put the working example and package settings alongside the project’s authoring instructions; the collaborative LaTeX writing workflow provides broader team context.
Step-by-step task: format quantities and a numeric table
This is an illustrative composite for typesetting, using invented values rather than observations. Each command applies the syntax in the official manual. The task deliberately separates three decisions: which input is a number or unit, how many digits to display, and how much space a table column reserves.
- Create a minimal document. Put the following complete source in a LaTeX document and compile it with your usual LaTeX workflow. It uses the standard article class and loads siunitx before the document begins.
\documentclass{article} \usepackage{siunitx} \begin{document} Length: \qty{12.345}{\milli\metre}. \end{document}
The expected quantity is 12.345 followed by the millimetre symbol, with the package controlling the number–unit presentation. This small example establishes that the package is loaded and the basic interface works before introducing a table or manuscript-specific options.
- Separate unit labels from values. Inside the document, use \unit{\milli\metre} when only a unit label is needed, and \num{12.345} when only the number is needed. Use \qty{12.345}{\milli\metre} when both belong together. The two arguments of qty have different jobs; the number belongs first.
- Express a compound unit through unit macros. Try \qty{2.5}{\metre\per\second}. Then compare \qty[per-mode = symbol]{2.5}{\metre\per\second}. The manual documents reciprocal-power and slash presentation through the per-mode setting. The input still describes the same number and unit; the presentation of the denominator changes.
- Apply rounding locally. Compare \num{12.345} with \num[round-mode = places, round-precision = 2]{12.345}. The latter prints 12.35 under the documented default rounding behavior. Using a local optional argument makes the comparison explicit without changing unrelated numbers elsewhere.
- Build the numeric table. Insert the following tabular environment inside the document. The left column contains sample labels; the S column contains plain numeric input. Braces protect its text heading from numeric parsing.
\begin{tabular}{l S[table-format = 2.3]} Sample & {Length (mm)} \\ A & 2.300 \\ B & 12.345 \\ C & 0.125 \\ \end{tabular}
Here table-format = 2.3 reserves room for two integer digits and three decimal digits. It is a layout model, not an instruction to report every value to three decimal places. These particular inputs already contain three decimal digits; changing an input to 2.3 provides a useful comparison between the input’s digits and the reserved column space.
- Check each kind of output independently. Inspect the prose quantity, the compound unit and the table’s decimal alignment. If a formatting rule should apply across the manuscript, set it with \sisetup in the preamble. For example, \sisetup{output-decimal-marker = {.}} explicitly requests a decimal point. Retain local options when only one number needs different treatment.
For repeated values, the manual provides \qtylist{0.13;0.67;0.80}{\milli\metre} and \qtyrange{0.13}{0.67}{\milli\metre}. A list uses semicolons between values inside one number argument; a range uses two separate number arguments followed by the unit. Both interfaces let related values share formatting controls rather than assembling their punctuation and units manually.
Output and how to read it
Read siunitx output as a formatted representation of the input. The number parser recognizes decimal markers and exponent notation; the unit formatter handles unit symbols and their combinations; the S column aligns numeric material. A useful review follows those layers in the same order, so a change in column width is not mistaken for a change in numerical content.
Rounding versus reserved table space
round-mode = places controls decimal places, while round-mode = figures controls significant figures. The accompanying round-precision supplies the count. The manual also documents none and uncertainty rounding modes. Select the mode deliberately: asking for two decimal places is a different instruction from asking for two significant figures.
By contrast, table-format describes the space reserved for components of a table number, including signs and exponents when specified. The manual’s examples distinguish unsigned, signed, uncertainty-bearing and exponent-bearing layouts. If negative values enter a column, its model should reserve a sign rather than assuming the earlier unsigned layout covers the changed data.
The documented round-pad option defaults to true, so enabling rounding can extend short numbers with trailing zeros. Those zeros are a formatting result. Treat the reporting precision as a scientific choice made before selecting the corresponding display settings; do not infer additional measurement precision from padding.
Uncertainty and decimal-marker checks
The manual accepts both compact uncertainty input such as \num{9.99(9)} and separate input such as \num{9.99 +- 0.09}. In this example the parenthesized uncertainty applies to the last displayed digits: it corresponds to 0.09. The interface can print uncertainty in different forms through its uncertainty-mode option; it does not establish what statistical interpretation the author intends.
For decimal-marker presentation, \num[output-decimal-marker = {,}]{1.23} requests a decimal comma. Current documentation also describes automatic defaults from document language information. An explicit output-decimal-marker setting takes precedence. Inspect the result after combining package settings with a multilingual document rather than assuming input punctuation fixes the output convention.
Special symbols have their own context. For the Å symbol and its package-specific considerations, see angstrom commands in LaTeX. Keep that symbol question separate from the table and rounding controls covered here.
Troubleshooting
The package or command is unavailable
Check that siunitx is present in the active TeX distribution and that its usepackage declaration appears in the preamble. Compare the failing document with the minimal example above. This isolates package loading from the extra classes, macros and packages in a full manuscript. The official CTAN entry links both distribution information and documentation.
When an older document works differently, inspect its command and option names against the manual’s upgrading section. The manual explains that version 3 revised several interfaces and maps many older options to newer names with log warnings. Read those warnings before replacing working scientific content or applying an option copied from an unrelated example.
A table heading is treated like a number
Protect text in an S cell with braces, as in {Length (mm)}. The manual says the column detects surrounding material, but material that could be confused with part of a number needs protection. Keep numeric entries as numeric input and compare the heading against the braced example before changing the column’s parser.
If decimals align but signs or exponents do not fit, inspect table-format. A model that reserves only integer and decimal digits has not reserved every possible component. Adjust the model to the actual input forms. Turning rounding on is a separate operation and does not substitute for declaring sufficient layout space.
The number argument contains more than a number
Keep the unit in the unit argument of qty instead of placing it inside num. The manual provides parse-numbers = false for cases needing arbitrary TeX code rather than numeric parsing, but disabling parsing changes what the package can process. Use the dedicated number, unit or quantity interface first; disable parsing only for an intentional literal-expression task.
Another package already defines qty
The compatibility section specifically documents a conflict when physics is loaded before siunitx: siunitx then omits its qty definition. The manual permits its older SI command as a drop-in alternative in that situation. This is a compatibility exception to the recommendation to use qty in new documents, so check package ownership before interpreting an unexpected qty result as a unit-formatting failure.
Free alternatives
These openly licensed LaTeX packages cover related tasks. The table reports capabilities described in their CTAN entries; it does not imply that their commands or option names can be substituted directly for siunitx. Match the documented task first, then use that package’s own manual for syntax.
| Package | Documented task | Scope of this alternative | Official source |
|---|---|---|---|
| numprint | Number grouping, configurable decimal and product signs, exponent formatting and rounding. | Its entry also describes optional upright units and tabular alignment: a related number-formatting workflow. | CTAN: numprint |
| units | Physical-unit typesetting using nicefrac. | A unit-presentation package distributed as a bundle with nicefrac. | CTAN: units |
| dcolumn | Decimal alignment in tabular columns through an array-based D column. | A table-column tool in the LaTeX required tools bundle. | CTAN: dcolumn |
The downloadable data table below serves a different purpose: it maps siunitx input and output checks to documentation sections. Use it as a review aid for the worked example, rather than as a ranking of software or an assertion that one typesetting choice establishes scientific correctness.
Sources
- CTAN, siunitx package catalog: maintainer, license, distribution availability and official documentation links. Checked 2026-11-16.
- Joseph Wright, siunitx user-manual source, CTAN mirror: Using the package, number processing and printing, tabular material, localization, upgrading, compatibility and installation sections. Checked 2026-11-16.
- Joseph Wright, official siunitx repository and README: package purpose and license. Checked 2026-11-16.
- CTAN, numprint: number formatting, rounding, unit argument and table features. Checked 2026-11-16.
- CTAN, units: physical-unit typesetting, nicefrac bundle and license. Checked 2026-11-16.
- CTAN, dcolumn: decimal-aligned D columns and LaTeX tools distribution. Checked 2026-11-16.
Data: siunitx manuscript input and output validation map
An original review map compiled from the siunitx user manual and CTAN package catalog. It pairs each documented interface with a specific input or output check for manuscript authors; the examples are typesetting checks, not observed research measurements.
| Task | Documented interface | Review check | Evidence section |
|---|---|---|---|
| Package access | TeX Live or MiKTeX package manager | Confirm siunitx is available in the active distribution. | CTAN siunitx catalog; manual: Installation |
| Number without a unit | num | Keep unit input outside the number argument; inspect decimal and exponent presentation. | Manual: Using the package / Numbers |
| Unit without a value | unit | Inspect the unit symbol or compound unit separately from a numerical value. | Manual: Using the package / Units |
| Number and unit together | qty | Supply the number first and the unit second; inspect their combined presentation. | Manual: Using the package / Units |
| Display rounding | round-mode and round-precision | Distinguish decimal places from significant figures; inspect any padding. | Manual: Number processing / round-mode, round-precision, round-pad |
| Numeric table layout | S column and table-format | Protect text headings with braces and reserve space for the actual numeric components. | Manual: Tabular material; Tabular options / table-format |
| Decimal-marker override | output-decimal-marker | Inspect the requested point or comma independently of input punctuation. | Manual: Number printing; Localization |
Sources
- Joseph Wright: siunitx user-manual source (accessed 2026-11-16)
- CTAN: siunitx package catalog (accessed 2026-11-16)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







