standalone

standalone is a LaTeX class for setting one thing — a figure, a TikZ picture, a table — as a single page cropped to the size of its content. Its real value is less the cropping than the fact that one file has two faces: compile figure.tex on its own and you get a PDF of just the figure; \input it from a paper and the same file flows into the body without a character changed. The cropping machinery has a history, too. Before the crop option that is the default today, standalone used the preview package that grew out of Emacs’s AUCTeX — the very code that floats formula previews inside the editor. This page covers the class and package themselves: how border= behaves, multi and subpreambles, and the errors you actually hit. Turning the finished figure into a PNG or SVG belongs to another page.

Using one figure file both alone and inside a paper

Once a document grows, you want the figures in their own files. But compiling such a file on its own means writing the scaffolding — \documentclass, \begin{document} — every time, and the output is the figure sitting in a corner of a large white body-text page. The standalone class settles both at once. Put \documentclass{standalone} at the top of a figure file and it compiles by itself, with the output cropped to the size of the content — one page of PDF, DVI or PS, with no page number, header or footer.

% figure.tex — a figure that is its own document
\documentclass[tikz,border=2pt]{standalone}
\begin{document}
\begin{tikzpicture}
  \draw[thick,->] (0,0) -- (3,0) node[right] {$x$};
  \draw[blue,thick] (0,0) .. controls (1,2) .. (3,1);
\end{tikzpicture}
\end{document}

standalone comes in two halves: the class used in the figure file (\documentclass{standalone}) and the package loaded in the main document (\usepackage{standalone}). The class plays “set one piece on its own”; the package plays “bring that piece into the body”. It is the work of Martin Scharrer, and the version in TeX Live 2024 is v1.3b, dated October 2022. The class needs xkeyval; the package needs that plus currfile, gincltex, filemod and adjustbox. All of them ship with TeX Live and MiKTeX.

crop versus preview, and where the default is actually set

The default is crop, with a border of 0pt — but that default lives in the configuration file standalone.cfg, not in the class. standalone.cls itself defaults to preview and 0.50001bp, which is what v0.x did; then, just before option processing begins, standalone.cfg is read and overrides both with \standaloneconfig{crop} and \standaloneconfig{border=0pt}. The two-stage arrangement is useful: drop your own standalone.cfg into the project directory or a local TEXMF tree and you change the default for every standalone file in that environment. The bundled cfg is overwritten on every update, so keep your own settings in a separate file.

crop and preview are mutually exclusive: give both and the last one wins, and either of them forces float=false. The practical difference shows up when you measure. A figure holding nothing but a 2 cm × 1 cm rectangle, built on TeX Live 2024, comes out at 57.09 × 28.75 bp under the default crop. Now put one blank line before \end{document}: under crop nothing changes, but under preview the width jumps to 343.71 bp. The blank line reads as a paragraph break, so the content becomes a paragraph the full \linewidth wide. That is the classic “wide white space to the right of my figure”, and avoiding it is exactly why crop became the default. preview survives because it is the escape hatch when TikZ shadings misbehave under XeLaTeX.

Adding margin with border=, and how the values are read

The option you reach for most is border= (alias margin=). One value applies to all four sides, two to horizontal and vertical, four to left, bottom, right and top in that order. To pass several space-separated values, wrap the whole thing in braces: border={10pt 5pt}. A bare number with no unit is read as bp, the PostScript point. Measured on the same 57.09 × 28.75 bp figure, border=5pt gives 67.05 × 38.71 bp (5 pt, about 4.98 bp, on each side) and border={10pt 5pt} gives 77.02 × 38.71 bp. Because border and varwidth are not global settings, they can be changed later with \standaloneconfig{...} — in the preamble, or even mid-document when multi is enabled.

Getting several figures out of one file (multi)

By default, everything inside the document environment becomes one page. Turn on multi and each occurrence of a named environment is cropped onto a page of its own. That is why \documentclass[tikz]{standalone} is so convenient: internally the tikz option sets multi=tikzpicture and varwidth=false, so two tikzpicture environments in a row give a two-page PDF. (pstricks does the same for PSTricks.) To use your own environment, declare \standaloneenv{myfig} and put nothing outside it; add ignorerest only if you really must have material in between. There is also a math option that crops formulas one at a time, and it sets multi and ignoreempty together with a border of 0.50001bp.

The errors and symptoms you actually hit

Every standalone error has a clear cause, and you can walk back from the symptom to it. The most common is putting a figure environment inside the standalone file: with crop or preview active you get ! LaTeX Error: Not in outer par mode. or a “Float(s) lost” message. Cropping works by packing the content into a box, and a float cannot float inside a box. Since both crop and preview set float=false on their own, this error can only appear if you wrote float=true by hand afterwards. Keep floats in the main document and leave only the drawing itself in the standalone file.

• Wide white space to the right of the figure. The content became a paragraph. Delete the blank line (or a stray \par) before \end{document}, add varwidth, or declare the environment with multi and \standaloneenv.
• The right-hand side is clipped. The varwidth maximum (by default \linewidth) is too narrow. Widen it, as in varwidth=15cm, or switch it off with varwidth=false.
• An option value is rejected. Anything other than true or false on a boolean key stops the run with, for example, ! Class standalone Error: Invalid value 'maybe' for boolean key 'crop'.
• An unwanted page appears in a multi-page file. You are using multi and something is being typeset outside the declared environments. Remove it, or enable ignorerest.
• Cropping misbehaves on the DVI route. In DVI mode crop emits PostScript commands, and the manual itself calls that code experimental. Under plain latex, preview is sometimes the steadier choice.

The package side: pulling the figure in with \input

Load \usepackage{standalone} as early as possible in the main document’s preamble and the package redefines \documentclass so that everything from an \input figure file’s \documentclass down to its \begin{document} is skipped. The figure file’s document environment is treated as a plain TeX group, and anything after \end{document} is ignored as well; so only the content of the figure file flows into the body. There is one prerequisite: the main document must load every package the figure files need. Since the figure file’s preamble is skipped, tikz and friends can only be loaded by the main file.

\documentclass{article}
% load the standalone package early
\usepackage{standalone}
% and everything the sub-files need
\usepackage{tikz}

\begin{document}
\begin{figure}
  \input{figure}%  the standalone file from above
  \caption{A sub-file}
\end{figure}
\end{document}

If copying preambles by hand is tedious, \usepackage[subpreambles=true]{standalone} collects them for you: each figure file’s preamble is gathered into an auxiliary file and pulled into the main document on the next run. Add sort and the packages each figure loads, with their options, are accumulated without duplicates and loaded through \PassOptionsToPackage, which avoids option clashes. If you would rather transcribe them yourself, print writes the list out — but it is a collection-only mode, and as the message Package standalone Warning: Running 'standalone' package in sub-preamble print mode. All body content of file 'figure.tex' is ignored! says outright, the body is not typeset.

\includestandalone and mode=: source or image

Write \includestandalone{figure} instead of \input and the package option mode= decides how the figure arrives. The values are tex (include the source — the default), image (include an existing PDF or EPS with \includegraphics), image|tex (image if there is one, source otherwise), build (build it every time), buildmissing (build only if the image is absent) and buildnew (build only if the source is newer; this does not work under XeLaTeX). The point is speed: a complicated figure need not be re-typeset on every run of the main document. Only the three build modes call an external command, and those need -shell-escape. The manual states plainly that if the build fails, a warning is issued and the source is included instead.

Everything downstream from here — turning the cropped PDF into a PNG or SVG, trimming an existing PDF with pdfcrop, driving dvisvgm, the settings you hand to convert= — belongs to the page on exporting figures as images. The one thing to carry away from the class side is that not making the margin is faster and more accurate than cutting it off afterwards.

Fitting standalone into a project

In a real paper, treating each standalone file as the source of a figure, in a form that can be checked apart from the text, pays off. Keep the main file as paper.tex, the figures under figures/, and let the text say only \input{figures/energy-flow}. Whoever revises a figure can then compile figures/energy-flow.tex on its own, while the main document manages nothing but captions, numbering and references. In review, attach that one-page PDF and run a figures-only pass: the drawing improves without waiting for the whole manuscript to rebuild.

paper.tex
standalone.cfg          # optional: your own defaults for every figure
figures/
  energy-flow.tex
  apparatus-layout.tex
  timing-diagram.tex

When a figure’s contents should follow the same typesetting rules as the body, match the underlying class with class=. For a figure carrying Japanese labels, \documentclass[class=jsarticle,border=5pt]{standalone} under upLaTeX — or class=ltjsarticle under LuaLaTeX — lines the inter-character spacing and typefaces up with the main text. The class and package also share \ifstandalone, \IfStandalone{when alone}{when included} and \onlyifstandalone{...}, which let you show a scale bar or a debugging frame only in the figure file, in a single line.

How subfiles and TikZ external differ

Two mechanisms serve similar ends, and both run in the opposite direction. With subfiles, a sub-file imports the main document’s preamble; standalone does the reverse, letting sub-file preambles be gathered into the main document. So standalone suits reusing one figure across several documents — a paper, a talk, a thesis — while subfiles suits a chapter-by-chapter split where main and sub-file correspond one to one. TikZ’s external library writes temporary images out from the main file, which again runs the other way. That said, \includestandalone[mode=buildnew] gives you essentially the same “cache the expensive drawing” effect while keeping the figure a self-contained file.