The TikZ and PGF Packages
Manual for version 3.1.10

TikZ Library external ¶

\usetikzlibrary{external} % LaTeX and plain TeX
\usetikzlibrary[external] % ConTeXt

This library provides a high-level automatic or semi-automatic export feature for TikZ pictures. Its purpose is to convert each picture to a separate pdf without changing the document as such.

It also externalizes \label information (and other aux file related stuff) using auxiliary files.

\tikzexternalize[⟨optional arguments⟩] ¶

This command activates the externalization. It installs commands to replace every TikZ-picture. It needs to be called before \begin{document} because it may need to install its separate shipout routine.

The ⟨optional arguments⟩ can be any of the keys described below.

Note that the generation/modification of auxiliary files like .aux, .toc etc. is usually suppressed while a single image is externalized (details for \label support follow).

It is also possible to write \tikzexternalize{⟨main job name⟩} if the argument is delimited by curly braces. This case is mainly for backwards compatibility and is no longer necessary. Since it might be useful in rare circumstances, it is documented in section 52.4.5.

A detailed description about the process of externalization is provided in section 52.4.5.

\tikzexternalrealjob ¶

After the library is loaded, this macro will always contain the correct main job’s name (in the example above, it is main). It is to be used instead of \jobname when the externalization is in effect.

\pgfactualjobname ¶

Once \tikzexternalize has been called, \pgfactualjobname contains the name of the currently generated output file (which may be main or main-figure0 or main-figure1 in our example above).

\jobname ¶

The value of \jobname is one of \tikzexternalrealjob or \pgfactualjobname, depending on the configuration. In short: if auxiliary file support (\label and \ref) is activated, \jobname=\tikzexternalrealjob (since that’s the base file name of auxiliary files).

/tikz/external/system call={⟨template⟩}(no default) ¶

A template string used to generate system calls. Inside of {⟨template⟩}, the macro \image can be used as placeholder for the image which is about to be generated while \texsource contains the main file name (in truth, it contains \input{⟨main file name⟩}, but that doesn’t matter).

The default depends on the value of \pgfsysdriver. For pgfsys-pdftex.def, it is

copy
\tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error
-interaction=batchmode -jobname "\image" "\texsource"}}


where \tikzexternalcheckshellescape inserts the value of the configuration key shell escape if and only if the current document has been typeset with -shell-escape⁶.

Other drivers result in slightly different calls. There is support for lualatex, xelatex, and dvips. The precise values are written to the .log file as soon as you attempt to compile a document.

The argument {⟨template⟩} will be expanded using \edef, so any control sequences will be expanded. During this evaluation, ‘\\’ will result in a normal backslash, ‘\’. Furthermore, double quotes ‘"’, single quotes ‘'’, semicolons and dashes ‘-’ will be made to normal characters if any package uses them as macros. This ensures compatibility with the german package, for example.

/tikz/external/shell escape={⟨command-line arg⟩} (no default, initially -shell-escape) ¶

Contains the command line option for latex which enables the \write18 feature. For TeX-Live, this is -shell-escape. For MiKTeX, you should use \tikzexternalize[shell escape=-enable-write18].

/tikz/external/aux in dpth={⟨boolean⟩} (no default, initially true) ¶

Allows to enable or disable the feature which handles references and labels as part of image externalization. Disabling it will safe one \newwrite command, i.e. a write register.

Also see the disable dependency files feature.

Here are some implementation details on how references within/from external graphics work for those who would like to know the details:

For point a), a \ref inside of an externalized graphics works by reading the main document’s .aux file. To this end, the standard mode=convert with system call detects such references and reschedules the externalization to \end{document}.⁷ Other values of mode require just one attempt to externalize the picture.

Note that \pageref is not supported (sorry).

Point b) works as follows: a \label inside of an externalized graphics causes the external library to generate separate auxiliary files for every external image. These files are called ⟨imagename⟩.dpth. The extension .dpth indicates that the file also contains the image’s depth (the baseline key of TikZ). Furthermore, anything which would have been written to an .aux file will be redirected to the .dpth file – but only things which occur inside of the externalized tikzpicture environment. When the main document loads the image, it will copy the .dpth file into the main .aux file. Then, successive compilations of the main document contain the external \label information. In other words, a \label in an external graphics needs the following work flow:

• 1. The external graphics needs to be generated together with its .dpth (usually automatically by TikZ).

• 2. The main document includes the external graphics and copies the .dpth content into its main .aux file.

• 3. The main document needs to be translated once again to re-read its .aux file⁸.

This does also work if a \label/\ref combination is implemented itself by a tikzpicture (a feature offered by pgfplots).

/tikz/external/prefix={⟨file name prefix⟩} (no default, initially empty) ¶

A shortcut for \tikzsetexternalprefix{⟨file name prefix⟩}, see below.

\tikzsetexternalprefix{⟨file name prefix⟩} ¶

Assigns a common prefix used by all file names. For example,

copy
\tikzsetexternalprefix{figures/}


will prepend figures/ to every external graphics file name.

Please note that \tikzsetexternalprefix is the only way to assign a prefix in case you want to prepare your document for environments where pgf is not installed (see section 52.5).

\tikzsetnextfilename{⟨file name⟩} ¶

Sets the file name for the next TikZ picture or \tikz short command. It will only be used for the next picture.

Pictures for which no explicit file name has been set (or the next file name is empty) will get automatically generated file names.

Please note that prefix will still be prepended to {⟨file name⟩}.

copy
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize[prefix=figures/] % activate

\begin{document}

\tikzsetnextfilename{trees}
\begin{tikzpicture} % will be written to 'figures/trees.pdf'
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}

\tikzsetnextfilename{simple}
A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'figures/simple.pdf'

\begin{tikzpicture} % will be written to 'figures/main-figure0.pdf'
\draw[help lines] (0,0) grid (5,5);
\end{tikzpicture}
\end{document}


copy
pdflatex -shell-escape main


/tikz/external/figure name={⟨name⟩}(no default) ¶

Same as \tikzsetfigurename{⟨name⟩}.

\tikzsetfigurename{⟨name⟩} ¶

Changes the names of all following figures. It is possible to change figure name during the document either using \tikzset{external/figure name={⟨name⟩}} or with this command. A unique counter will be used for each different {⟨name⟩}, and each counter will start at \(0\).

The value of prefix will be applied after figure name has been evaluated.

copy
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize % activate

\begin{document}

\begin{tikzpicture} % will be written to 'main-figure0.pdf'
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}

{
\tikzsetfigurename{subset_}
A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf'

\begin{tikzpicture} % will be written to 'subset_1.pdf'
\draw[help lines] (0,0) grid (5,5);
\end{tikzpicture}
}% here, the old file name will be restored:

\begin{tikzpicture} % will be written to 'main-figure1.pdf'
\draw (0,0) -- (5,5);
\end{tikzpicture}
\end{document}


The scope of figure name ends with the next closing brace.

Remark: Use \tikzset{external/figure name/.add={prefix_}{_suffix_}} to add a prefix_ and a _suffix_ to the actual value of figure name.

\tikzappendtofigurename{⟨suffix⟩} ¶

Appends ⟨suffix⟩ to the actual value of figure name.

It is a shortcut for \tikzset{external/figure name/.add={}{⟨suffix⟩}} (a shortcut which is also supported if TikZ is not installed, see below).

\tikzpicturedependsonfile{⟨file name⟩} ¶

Adds a dependency for the next picture which is about to be externalized. If the command is invoked within a picture environment, it adds a dependency for the surrounding picture. Dependencies are written into ⟨target file⟩.dep in the format

⟨target file⟩.\tikzexternalimgextension: ⟨file name⟩.

The effect is that if ⟨file name⟩ changes, the external graphics associated with the picture shall be remade.

This command uses the contents of \tikzexternalimgextension to check for graphics. If you encounter difficulties with image extensions, consider redefining this macro (after \tikzexternalize).

Limitations: this command is currently only supported for mode=list and make and the generated makefile.

\tikzexternalfiledependsonfile{⟨external graphics⟩}{⟨file name⟩} ¶

A variant of \tikzpicturedependsonfile which adds a dependency for an ⟨external graphics⟩. The argument ⟨external graphics⟩ must be the path as it would have been generated by the external library, i.e. without file extension but including any prefixes.

/tikz/external/disable dependency files(no value) ¶

Allows to (irreversibly) disable the generation of file dependencies. Disabling it will safe one \newwrite command, i.e. a write register. Note that the write register is only allocated if the feature has been used at all. This key needs to be provided as argument to \tikzexternalize (or it needs to be set before calling \tikzexternalize).

Also see the aux in dpth key.

/tikz/external/force remake={⟨boolean⟩} (default true) ¶

A boolean which is used to customize the up-to-date checks of all following figures. Every up-to-date check will fail, resulting in automatic regeneration of every following figure.

copy
\tikzset{external/force remake}
\begin{tikzpicture}
\draw (0,0) circle(5pt);
\end{tikzpicture}


You can also use force remake inside of a local TeX group to remake only selected pictures. The example

copy
\tikz \draw (0,0) -- (1,1);

{
\tikzset{external/force remake}
\begin{tikzpicture}
\draw (0,0) circle(5pt);
\end{tikzpicture}
}

\tikz \draw (0,0) -- (1,1);


will only apply force remake to the second figure.

Up-to-date checks are applied for mode=convert with system call and the makefile generated by mode=list and make.

/tikz/external/remake next={⟨boolean⟩} (default true) ¶

A variant of force remake which applies only to the next image.

/tikz/external/export next={⟨boolean⟩} (default true) ¶

A boolean which can be used to disable the export mechanism for single pictures.

/tikz/external/export={⟨boolean⟩} (no default, initially true) ¶

A boolean which can be used to disable the export mechanism for all pictures inside of the current TeX-scope.

copy
\begin{document}
\begin{tikzpicture} % will be exported
...
\end{tikzpicture}

{
\tikzset{external/export=false}
\begin{tikzpicture} % won't be exported
...
\end{tikzpicture}
...
}

\begin{tikzpicture} % will be exported
...
\end{tikzpicture}
\end{document}


For LaTeX, the feature lasts until the next \end{⟨\(\cdot \)⟩} (this holds for every call to \tikzset).

/tikz/external/up to date check={⟨choice⟩} (no default, initially md5) ¶

The external lib has to decide when some existing figure is up-to-date. In such a case, it can be used without remaking it. Outdated pictures will be remade.

The key up to date check allows to choose among a couple of heuristics which are supposed to catch the most important reasons to remake a figure.

The up to date check can be overrule by any of the force remake or remake next keys: if one of them is true, the figure is not up-to-date.

The choice simple is based on the existence of the file: the file is up-to-date if and only if it exists.

The choice md5 generates an MD5 checksum of the picture for which the up-to-date check is running. The MD5 is compared against the MD5 of the previous run, which, in turn, will be written into an extra file with the extension .md5. This file will be modified if and only if the MD5 comparison indicates a difference. The MD5 computation is based on the pdfTeX method \pdfmdfivesum. If it is unavailable for some reason, the choice diff will be used instead.

The choice diff is the same as MD5 – except that it compares the picture content as-is instead of a hash. The .md5 file will be used to compare an old version with the current one – but its content is some “normalized” version of the picture for internal use.

Attention: the content–based strategies md5 and diff operate on the picture content – and only on the picture content. Here, “picture content” only includes the top–level tokens; no expansion is applied and no included files are part of the strategies. If you change preamble styles, you have to rebuild the figures manually (for example by deleting the generated graphics files). If you have include files, consider using \tikzpicturedependsonfile and its variants. Since this key provides heuristics, you should always remake your figures before you finally publish your document. Example: Suppose we have the following picture which depends on a command \mycommand:

copy
\def\mycommand{My comment}

\begin{tikzpicture}

\node at (0,0) {\mycommand};

\end{tikzpicture}


What happens if you change “My comment” to “My super comment”? Well, external will not pick it up; you will need to handle this manually. However, if you modify anything between \begin{tikzpicture} and \end{tikzpicture}, the external library will pick it up and regenerate the picture.

The up to date check is applied for mode=convert with system call and mode=list and make.

\tikzexternaldisable ¶

Allows to disable the complete externalization. While export next will still collect the contents of picture environments, this command uninstalls the hooks for the external library completely. Thus, nested picture environments or environments where \end{tikzpicture} is not directly reachable won’t produce compilation failures – although it is not possible to externalize them automatically.

The externalization remains disabled until the end of the next TeX group (or environment) or until the next call to \tikzexternalenable.

\tikzexternalenable ¶

Re-enables a previously running externalization after \tikzexternaldisable.

/tikz/external/figure list={⟨boolean⟩} (no default, initially true) ¶

A boolean which configures whether a figure list shall be generated. A figure list is an output file named {⟨jobname⟩}.figlist which is filled with file names of each figure, one per line.

This file is not used by TeX anymore, its purpose is to issue the required conversion commands pdflatex -jobname {⟨picture file name⟩} {⟨main file⟩} manually (or in a script). See section 52.4.5 for the details about the expected system call (or activate mode=convert with system call and inspect your log file).

copy
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}

\usetikzlibrary{external}
\tikzexternalize[
mode=graphics if exists,
figure list=true,
prefix=figures/]

\begin{document}

\tikzsetnextfilename{trees}
\begin{tikzpicture}
\node {root}
child {node {left}}
child {node {right}
child {node {child}}
child {node {child}}
};
\end{tikzpicture}

\tikzsetnextfilename{simple}
A simple image is \tikz \fill (0,0) circle(5pt);.

\begin{tikzpicture}
\draw[help lines] (0,0) grid (5,5);
\end{tikzpicture}
\end{document}


copy
pdflatex main


generates main.figlist containing

copy
figures/trees
figures/simple
figures/main-figure0


/tikz/external/mode={⟨choice⟩} (no default, initially convert with system call) ¶

Configures what to do with TikZ pictures (unless we are currently externalizing one particular image, in that case, these modes are ignored).

The preconfigured mode convert with system call checks whether external graphics files are up-to-date and includes them if that is the case. Any picture which is not up-to-date will be generated automatically using a system call. The system call can be configured using the system call template. The up-to-date check is applied according to the up to date check key. As soon as convert with system call is set, the figure list will be disabled – such a file is not required. In case you still need or want it, you can enable it after setting mode.

Please note that system calls may be disabled for security reasons. For pdflatex, they can be enabled using

copy
pdflatex -shell-escape


while other TeX variants may need other switches. The feature is sometimes called \write18.

The choice only graphics always tries to replace pictures with external graphics. It is an error if the graphics file does not exist.

The choice no graphics (or, equivalently, only pictures) typesets TikZ pictures without checking for external graphics.

A mixture is graphics if exists, it checks whether a suitable graphics file exists and includes it if that is the case. If it does not exist, the picture is typeset using TeX.

Mode list only skips every TikZ picture; it only generates the file {⟨main file⟩}.figlist containing file names for every picture, the contents of any picture environment is thrown away and a replacement text is shown. This implies figure list=true. See also the list and make mode which includes available graphics.

The mode list and make is similar to list only: it generates the same file {⟨main file⟩}.figlist, but any images which exist already are included as graphics instead of ignoring them. Furthermore, this mode generates an additional file: {⟨main file⟩}.makefile. This allows to use a work flow like

copy
% step 1: generate main.makefile:
pdflatex main
% step 2: generate ALL graphics on 2 processors:
make -j 2 -f main.makefile
% step 3: include the graphics:
pdflatex main


This last make method is optional: list and make just assumes that images are generated somehow (not necessarily with the generated makefile). The generated makefile allows parallel externalization of graphics on multi-core systems and it supports any file dependencies configured with \tikzpicturedependsonfile. Furthermore, it respects the force remake and remake next keys.

/tikz/external/verbose IO={⟨boolean⟩} (no default, initially true) ¶

A boolean which configures whether I/O operations shall be listed in the logfile.

/tikz/external/verbose optimize={⟨boolean⟩} (no default, initially true) ¶

A boolean which configures whether optimization operations shall be listed in the logfile.

/tikz/external/verbose={⟨boolean⟩} (no default, initially true) ¶

Sets all verbosity flags to ⟨boolean⟩.

/tikz/external/optimize={⟨boolean⟩} (no default, initially true) ¶

Configures whether the conversion process shall be optimized. This affects only the case when \jobname differs from the main file name, i.e. when single pictures are converted.

In that case, the main file is compiled as usual – but everything except the selected picture is thrown away. If optimization is enabled, all other pictures won’t be processed at all. Furthermore, expensive commands which do not contribute to the selected picture will be thrown away as well.

The default implementation discards \includegraphics commands which are not inside of the selected picture to reduce conversion time.

It is possible to add commands which shall be optimized away, see below.

/tikz/external/optimize command away=⟨\command⟩{⟨required argument count⟩}(no default) ¶

Installs commands to optimize ⟨\command⟩ away. As is described above, optimization applies to the case when single pictures are converted: one usually doesn’t need to process (probably expensive) commands which do not contribute to the selected picture.

The argument {⟨required argument count⟩} is either empty or a non-negative integer between \(0\) and \(9\). It denotes the number of arguments which should be consumed after ⟨\command⟩. In any case, one argument in square brackets after the command will be recognized as well. To be more precise, the following cases for arguments of ⟨\command⟩ are supported:

• 1. If {⟨required argument count⟩} is empty (the default), ⟨\command⟩ may take one optional argument in square brackets and one in curly braces (which is also optional).

• 2. If {⟨required argument count⟩} is not empty, {⟨\command⟩} may take one optional argument in square brackets. Furthermore, it expects exactly {⟨required argument count⟩} following arguments.

Example:

copy
\tikzset{external/optimize command away=\includegraphics}


copy
\newcommand{\myExpensiveMacro}[1]{Very expensive!}

\tikzset{external/optimize command away=\myExpensiveMacro}


copy
\newcommand{\myExpensiveMacroWithThreeArgs}[3]{Very expensive!}

\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{3}}


copy
% A command with optional argument:
\newcommand{\aFurtherExample}[3][]{Very expensive!}

% consume only two arguments: the first optional one will be processed
% anyway:
\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{2}}


The argument ⟨\command⟩ must be the name of a single macro. Any occurrence of this macro, together with its arguments, will be removed.

copy
\begin{tikzpicture}
% this picture is currently converted!
\end{tikzpicture}

This here is outside of the converted picture and contains \myExpensiveMacro. It will be discarded.

This call: \myExpensiveMacro[argument=value]{Argument} as well.
And this here: \myExpensiveMacro{Argument} also.


The default is to optimize \includegraphics away.

This key is actually a style which sets the optimize/install and optimize/restore keys.

/tikz/external/optimize/install(no value) ¶

A command key which contains code to install optimizations. You can append code here (or clear the macro) if you need to modify the optimization.

/tikz/external/optimize/restore(no value) ¶

A command key which contains code to undo optimizations. You can append code here (or clear the macro) if you need to modify the optimization.

/tikz/external/only named={⟨boolean⟩} (no default, initially false) ¶

If enabled, only pictures for which file names have been set explicitly using \tikzsetnextfilename will be considered, no file names will be generated automatically.

/pgf/images/include external(initially \pgfimage{#1}) ¶

This command key constitutes the public interface to exchange the \includegraphics command used for the image inclusion. If can be overwritten using include external/.code={⟨TeX code⟩}.

Its description can be found in the corresponding basic layer documentation in section 111.4.

Just one example here: you can use

copy
\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}


to manually change the viewport (bounding box) for included graphics.

Another example (of probably limited use) is

copy
\pgfkeys{/pgf/images/include external/.code={\href{file:#1}{\pgfimage{#1}}}}


which will generate a clickable hyperlink around the image. Clicking on it opens the single exported file⁹.

If you want to limit the effects of this key to just one externalized figure, use

copy
{
\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
\begin{tikzpicture}
...
\end{tikzpicture}
}% this brace ends the effect of `include external'


\tikzifexternalizing{⟨true code⟩}{⟨false code⟩} ¶

This command can be used to check whether an image is currently written to its separate graphics file (if the “grab” procedure is running). If so, the {⟨true code⟩} will be executed. If not, that means if the main document is being typeset normally, the {⟨false code⟩} will be invoked.

This command must be used after \tikzexternalize.

\tikzifexternalizingnext{⟨true code⟩}{⟨false code⟩} ¶

Like \tikzifexternalizing, but this variant also checks if the next following figure is the one which is about to be written to its separate graphics file.

/pgf/images/external info={⟨boolean⟩} (no default, initially false) ¶

If this key is activated, the size for any externalized image will be stored explicitly into the associated .dpth file.

When the file is included by \pgfincludeexternalgraphics (or automatically by the external library), the width is available as >\pgfexternalwidth and the height as \pgfexternalheight.