Tx · LaTeX & TikZ

How to Fix a Shell-Escape Error with PGFPlots

Published By the 9to5Science editorial team

At a glance

  1. 1. Find the trigger

    Check whether your document uses TikZ externalization or a PGFPlots feature that runs an external program such as gnuplot.

  2. 2. Enable shell escape

    Compile with the shell-escape option if the document needs to launch external commands.

  3. 3. Check the environment

    Confirm the output directory is writable and any required external program is installed.

  4. 4. Try without it

    Disable externalization or replace the external calculation if you do not want to allow shell commands.

A shell-escape error in a PGFPlots document usually means that something in the document is asking TeX to run an external program. A basic \addplot does not require shell escape, so the fix depends on what command or library is triggering the request.

The most common causes are TikZ’s external library, which runs TeX again to create separate figure files, and PGFPlots’ gnuplot support, which launches the gnuplot program. Find which feature your document uses before changing compiler settings.

What shell escape does

TeX normally runs in a restricted mode and cannot execute arbitrary operating-system commands. Shell escape lets TeX invoke external programs. This is useful for workflows such as generating cached figures, but it can also run unwanted commands if you compile an untrusted document.

A message such as runsystem(...): disabled or a message saying that shell escape is needed indicates that a command was blocked. The exact wording varies by TeX distribution and editor. The message usually identifies the command or generated file that points to the cause.

Enable shell escape for TikZ externalization

If your preamble contains \usetikzlibrary{external} and \tikzexternalize, TikZ is set to compile pictures separately. Compile with shell escape enabled. For example, with pdfLaTeX from a terminal:

pdflatex -shell-escape main.tex

A minimal externalized PGFPlots document is:

\documentclass{article}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}
\usetikzlibrary{external}
\tikzexternalize

\begin{document}
\begin{tikzpicture}
  \begin{axis}[xlabel={$x$}, ylabel={$y$}]
    \addplot[blue, domain=0:6.28, samples=100] {sin(deg(x))};
  \end{axis}
\end{tikzpicture}
\end{document}

Compile the document using the shell-escape option each time TikZ needs to generate or update an externalized figure. With latexmk, a common command is latexmk -pdf -shell-escape main.tex. In a graphical editor, look for the compiler’s command-line options and add the equivalent option for the TeX engine you use.

Externalization may also fail if its output folder does not exist or is not writable. If you configured a prefix such as \tikzexternalize[prefix=figures/], make sure the figures directory exists and your compiler can write to it. If compilation gets stuck using an old cached figure, delete the generated external figure files and compile again.

If the document uses gnuplot

PGFPlots can ask gnuplot to calculate data for a plot. For example, a plot command using the gnuplot handler launches an external program; it needs both shell escape and an installed gnuplot executable. Enabling shell escape alone will not fix an error saying that gnuplot cannot be found.

If you do not need gnuplot-specific features, you may be able to use a regular PGFPlots expression instead. For example, this plot is evaluated by PGFPlots and does not need shell escape:

\addplot[domain=0:6.28, samples=100] {sin(deg(x))};

Here, x is in radians for the sine function, so deg(x) converts it to degrees as required by the expression syntax. If your actual data or calculation needs gnuplot, install the program and make sure the compiler can find it.

Compile without shell escape

If you do not want TeX to run external commands, remove or disable the feature that requires them. For TikZ externalization, remove or comment out both \usetikzlibrary{external} and \tikzexternalize. The same basic plot then works as an ordinary inline figure:

\documentclass{article}
\usepackage{pgfplots}
\pgfplotsset{compat=1.18}

\begin{document}
\begin{tikzpicture}
  \begin{axis}[xlabel={$x$}, ylabel={$y$}]
    \addplot[blue, domain=0:6.28, samples=100] {sin(deg(x))};
  \end{axis}
\end{tikzpicture}
\end{document}

This example does not need shell escape. It also does not use TikZ externalization, so the figure is drawn during the normal document compilation.

Common mistakes

  • Assuming all PGFPlots figures need shell escape. Ordinary axis environments and many \addplot expressions work without it. Look for externalization or a command that launches another program.
  • Enabling shell escape but leaving out a required program. Gnuplot-based plotting still needs gnuplot installed and available to the compiler.
  • Changing the wrong compiler setting. Enable the option for the TeX engine that actually compiles the document, not just for a separate preview tool.
  • Allowing shell escape for an untrusted file. Shell escape permits external commands. Use it only when you trust the source and its dependencies; otherwise remove the feature that requires it.
  • Ignoring file permissions. Externalization writes files. Check that its output directory exists and is writable if the error refers to creating a file rather than running a command.

References

  1. The TikZ and PGF Packages: Externalization Library
  2. PGFPlots — A LaTeX Package to Create Normal/Technical Plots in LaTeX

Spotted an error? Send a correction. Read how we write and check articles in our editorial policy.