Glossaries and Acronyms in LaTeX: the glossaries and acronym Packages

A thesis needs a glossary, a list of abbreviations and often a list of symbols; a paper usually needs abbreviations that are spelled out on first use and shortened afterwards. LaTeX has three packages for this: glossaries (the complete solution, with an external sorting step), acronym (abbreviations only, no build step) and nomencl (a list of symbols built with makeindex). This guide shows how to set up each one, how the build works under makeglossaries and latexmk, how first-use expansion behaves, and the errors that catch most people.

The glossaries Package

Load glossaries after hyperref, call \makeglossaries in the preamble, and define every entry in the preamble before \begin{document}. Terms are defined with \newglossaryentry, abbreviations with \newacronym:

\documentclass{article}
\usepackage[colorlinks]{hyperref}       % hyperref first
\usepackage[acronym,toc,nonumberlist]{glossaries}
\makeglossaries

\newglossaryentry{latex}{
  name={LaTeX},
  description={A document preparation system built on top of the TeX
    typesetting engine}
}
\newglossaryentry{matrix}{
  name={matrix},
  plural={matrices},
  description={A rectangular array of numbers arranged in rows and columns}
}
\newacronym{gcd}{GCD}{greatest common divisor}
\newacronym{svd}{SVD}{singular value decomposition}

\begin{document}
\tableofcontents

\section{Introduction}
We compute the \gls{gcd} of two integers, then the \gls{gcd} again.
Every \gls{matrix} has a \gls{svd}; several \glspl{matrix} share one.
\Gls{latex} is used throughout.

\printglossary[type=\acronymtype, title={List of Abbreviations}]
\printglossary[title={Glossary}]
\end{document}

The first \gls{gcd} prints “greatest common divisor (GCD)”; the second prints “GCD”. \gls{matrix} prints “matrix”, \glspl{matrix} uses the plural key, and \Gls capitalises the first letter for the start of a sentence. Every entry that is used gets a page reference in the glossary unless you pass nonumberlist, and the toc option adds the glossaries to the table of contents.

The package options you will reach for most:

• acronym – put acronyms in their own glossary, \acronymtype, instead of the main one
• symbols – create a symbols glossary for a list of symbols
• toc, section=section – list the glossaries in the contents and set them as sections rather than chapters
• nonumberlist, nopostdot – drop the page numbers and the full stop after each description
• sort=def / sort=use – order by definition or first use instead of alphabetically
• style=long, style=tree, style=super – the glossary layout (list is the default)

The commands in the text

The “first use” flag is global: once \gls{svd} has expanded anywhere in the document, every later use is short. If you want the full form repeated at the start of each chapter, put \glsresetall after each \chapter. Note that \gls used in an abstract that is typeset before the main text counts as the first use, and that a \gls inside a figure caption or a floating table may be “used” out of reading order.

The Build Step: makeglossaries, makeindex and latexmk

This is where most problems come from. When you compile, \gls writes each used entry to main.glo (and acronyms to main.acn). Those files are unsorted; a separate program has to sort them and produce main.gls and main.acr, which \printglossaries reads on the next run. The full sequence is:

pdflatex main
makeglossaries main     % runs makeindex (or xindy) for every glossary
pdflatex main
pdflatex main           % once more to settle page numbers

makeglossaries is a Perl script shipped with the package. It reads main.aux to find out which glossaries exist and calls makeindex with the style file main.ist that \makeglossaries wrote, so you never have to type the makeindex incantation yourself. If you have no Perl (common on Windows), use makeglossaries-lite main, a Lua version with the same job, or call makeindex directly:

makeindex -s main.ist -t main.glg -o main.gls main.glo   % main glossary
makeindex -s main.ist -t main.alg -o main.acr main.acn   % acronyms

For languages with accented letters or non-Latin scripts, makeindex sorts badly; load the package with the xindy option and makeglossaries will call xindy instead.

Letting latexmk do it

latexmk does not know about glossaries by default, but a few lines in a .latexmkrc file in the project directory teach it when to run makeglossaries. This is the rule from the glossaries manual:

# .latexmkrc
add_cus_dep('glo', 'gls', 0, 'makeglossaries');
add_cus_dep('acn', 'acr', 0, 'makeglossaries');
sub makeglossaries {
  my ($base_name, $path) = fileparse( $_[0] );
  pushd $path;
  my $return = system "makeglossaries", $base_name;
  popd;
  return $return;
}

With that in place, latexmk -pdf main runs the whole sequence and repeats it until nothing changes. latexmk reads a latexmkrc or .latexmkrc from the directory it runs in, so the rule travels with the project. Overleaf ships an equivalent rule, which is why glossaries “just work” there; Octree compiles with latexmk too, so the same rule applies there as long as the latexmkrc file is part of your project, next to the main file.

Two ways to avoid the external tool

The automake package option makes glossaries call makeindex itself during the LaTeX run through shell escape, so running pdflatex main twice is enough:

\usepackage[acronym,automake]{glossaries}

makeindex is on TeX Live's restricted shell-escape list, so this works without --shell-escape; with the xindy option, or where shell escape is switched off entirely, nothing is called and the glossary stays empty. The second option needs no program at all: replace \makeglossaries with \makenoidxglossaries and \printglossaries with \printnoidxglossaries, and TeX sorts the entries itself after two runs. It is slower, has trouble with non-ASCII sort keys and offers fewer styles, but it is the easiest route for a short document.

Sorting and Symbol Glossaries

Entries are sorted alphabetically by their sort key, which defaults to the name. That breaks as soon as the name is a command, so a symbol entry should always set sort explicitly. A list of symbols is a glossary of type symbols whose names are the symbols themselves:

\usepackage[symbols,sort=def]{glossaries}
\makeglossaries

\newglossaryentry{c}{
  type=symbols,
  name={\ensuremath{c}},
  sort={c},
  description={speed of light in vacuum, $2.998\times10^{8}$ m/s}
}
\newglossaryentry{hbar}{
  type=symbols,
  name={\ensuremath{\hbar}},
  sort={hbar},
  description={reduced Planck constant}
}

\begin{document}
Energy $E = \gls{hbar}\omega$ and $E = m\gls{c}^2$.
\printglossary[type=symbols, title={List of Symbols}]
\end{document}

sort=def keeps the symbols in the order you defined them, which is usually what a physics or engineering thesis wants (grouped by topic rather than alphabetically). The entry also accepts a symbol key; styles such as long4col and super4col print it in its own column, which lets you keep a word as the name and show the symbol beside it.

glossaries-extra

glossaries-extra loads glossaries and adds a better abbreviation system, categories and the bib2gls workflow. Two things change: abbreviations are created with \newabbreviation and have switchable styles, and \newacronym now defaults to the short-nolong style (short form only, even on first use), so set the style you want explicitly:

\usepackage[colorlinks]{hyperref}
\usepackage[abbreviations]{glossaries-extra}
\makeglossaries
\setabbreviationstyle[acronym]{long-short}   % first use: long (SHORT)

\newacronym{cpu}{CPU}{central processing unit}
\newabbreviation{api}{API}{application programming interface}

\begin{document}
The \gls{cpu} and the \gls{api}; again the \gls{cpu} and \gls{api}.
\printabbreviations   % \printglossaries would print the same list
\end{document}

Other styles include short-long, long-short-sc (small-caps short form), long-short-desc (with a separate description for the list) and footnote (long form in a footnote on first use). The short/long accessors are \glsxtrshort, \glsxtrlong and \glsxtrfull. For large glossaries, bib2gls keeps the entries in a .bib file, sorts them in Java and includes only the ones you used, replacing makeglossaries entirely.

The Simpler acronym Package

If all you need is a list of abbreviations, the acronym package does it with no build step. Define the acronyms inside an acronym environment, which also typesets the list at that point; the optional argument is the longest short form and sets the column width:

\usepackage[printonlyused,withpage]{acronym}

\section*{List of Abbreviations}
\begin{acronym}[LSTM]
  \acro{api}[API]{application programming interface}
  \acro{cpu}[CPU]{central processing unit}
  \acro{lstm}[LSTM]{long short-term memory}
  \acrodefplural{cpu}[CPUs]{central processing units}
\end{acronym}

\section{Text}
The \ac{cpu} runs the \ac{api}. Later the \ac{cpu} is short.
Full again: \acf{cpu}. Short only: \acs{cpu}. Long only: \acl{cpu}.
Plural: \acp{cpu}. \acused{lstm} Now \ac{lstm} is treated as used.
\acresetall After reset: \ac{cpu}.

• \ac – long form (SHORT) on first use, SHORT afterwards
• \acf, \acs, \acl – full, short and long form on demand
• \acp, \acfp, \acsp, \aclp – plurals
• \acused{label} – mark as used without printing; \acresetall – expand everything again
• \acrodef – define an acronym outside the list (no entry is printed)

The printonlyused option drops acronyms that never appear in the text, withpage adds the page of first use, footnote puts the long form in a footnote instead of parentheses, and nohyperlinks switches off the links that are created when hyperref is loaded. The list is typeset wherever the environment sits, so put it where you want it to appear. The package has no sorting; entries print in the order you wrote them.

Nomenclature with nomencl

nomencl builds a list of symbols from \nomenclature commands scattered through the text, usually right after the equation that introduces each symbol:

\usepackage[intoc]{nomencl}
\makenomenclature
\renewcommand{\nomname}{List of Symbols}

\begin{document}
\tableofcontents
\section{Model}
The energy $E = mc^2$ where $m$ is the mass.
\nomenclature{$c$}{Speed of light in vacuum}
\nomenclature{$m$}{Mass of the particle}
\nomenclature[A]{$E$}{Energy}
\printnomenclature
\end{document}

Like glossaries, it needs makeindex, with the style file that comes with the package:

pdflatex main
makeindex main.nlo -s nomencl.ist -o main.nls
pdflatex main

# .latexmkrc rule
add_cus_dep('nlo', 'nls', 0, 'makenlo2nls');
sub makenlo2nls {
  system("makeindex -s nomencl.ist -o \"$_[0].nls\" \"$_[0].nlo\"");
}

The optional argument of \nomenclature is a sort prefix: entries are sorted by prefix first, then by symbol, so [A] puts a symbol before everything without a prefix and prefixes such as [G] for Greek letters and [S] for subscripts let you group the list. Redefine \nomgroup to print a heading for each prefix. intoc adds the list to the contents, and \printnomenclature[2cm] sets the width of the symbol column.

Which Package Should You Use?

Common Errors and Fixes

Quick Reference

Frequently Asked Questions

Why is my glossary empty or missing?

The glossaries package writes the entries you use to a .glo (and .acn) file and needs the external makeglossaries program to sort them into a .gls file that \printglossaries can read. If you only run pdflatex, the file never exists and the glossary is blank. Run pdflatex, then makeglossaries, then pdflatex twice; or let latexmk do it with a .latexmkrc rule; or use \makenoidxglossaries and \printnoidxglossaries so no external tool is needed.

What is the difference between the glossaries and acronym packages?

acronym handles abbreviations only: define them in an acronym environment, use \ac in the text, and the list is typeset where the environment appears, with no extra build step. glossaries also handles full glossary entries, symbol lists and multiple glossaries, with page references and many styles, but needs makeglossaries (or latexmk) to sort the entries. For a thesis with a glossary and a list of symbols use glossaries; for a paper that only needs abbreviations, acronym is simpler.

How do I make an acronym show its full form on first use only?

That is the default behaviour of \gls with \newacronym in glossaries and of \ac in the acronym package: the first use prints “long form (SHORT)” and later uses print only SHORT. To force the long form again, call \glsresetall (glossaries) or \acresetall (acronym), for example at the start of each chapter; \glsreset{label} resets a single entry.

Should hyperref be loaded before or after glossaries?

Before. glossaries detects hyperref at load time and turns every \gls into a link to the glossary entry; if hyperref is loaded afterwards the links are silently missing, with no warning to tell you why. The same order (hyperref first) applies to glossaries-extra and nomencl; the acronym package also hyperlinks when hyperref is already loaded.

How do I sort glossary entries in order of definition or first use instead of alphabetically?

Pass the sort package option: \usepackage[sort=def]{glossaries} sorts in the order entries are defined and sort=use in the order they are first used. The default sort=standard is alphabetical by the sort key, which is the name unless you set sort={...} on the entry, which you should do whenever the name contains a command such as \ensuremath.

Next Steps

Glossary sorted? These guides cover the other front- and back-matter jobs:

• LaTeX Hyperlinks – hyperref options, link colors and why it has to be loaded before glossaries
• LaTeX Footnotes – Footnotes, including the footnote style of acronym and glossaries-extra
• Greek Letters and Math Symbols – The symbols you will be listing in a nomenclature
• LaTeX Tables – Build a hand-made abbreviation table when a package is overkill
• LaTeX Page Numbering – Roman numerals for the front matter where glossaries usually live
• Learn LaTeX – Complete beginner tutorial covering all the basics

Free LaTeX Tools

• LaTeX Preview – Test acronym and glossary code with a live PDF preview
• Table to LaTeX – Build a manual list of abbreviations as a table
• LaTeX Symbols Reference – Look up the symbols for your nomenclature