[Tex/LaTex] How to enable shell-escape

big-listeditorsshell-escape

I need to enable shell escape for a package that I want to use. What is shell escape exactly, and how do I enable it in my editor or compiling toolchain?

Links to answers for different editors/toolchains, in alphabetical order:

Note: this is a FAQ post. Related Meta question: Canonical question on enabling shell-escape in different editors. Please add an answer for your own editor/toolchain if it is missing. Thank you!

When adding an answer, please indicate if the setting is permanent or per-document, and/or describe how you can add a button, shortcut, menu item, etc. to make it easy to switch between shell-escape and regular compilation.

Best Answer

General information: what is shell escape?

A number of LaTeX packages need to use external tools to function. Such a tool is called from the LaTeX source code using a system command. However, by default the unrestricted use of external system calls is not permitted by LaTeX. This is a security measure to prevent malicious LaTeX code to delete files, change system settings, allow remote access, et cetera. Therefore, when you try to compile a document using default settings, you will get an error message and/or wrong output if you use a package that needs an external tool.

To be able to use such packages you can change the security settings for the current document. This is done by using a compiler flag called shell-escape. Note that this introduces the risks outlined above, so you should only use this flag if you trust the source code that you are trying to compile.

Some example packages that use shell escape:

  • minted
  • svg
  • asypictureB
  • imakeidx
  • gnuplottex
  • graphviz
  • tikz (externalize)
  • standalone (convert option)
  • pgfplots (gnuplot)

The default setting is usually "Restricted Shell escape" this allows a small number of programs to be called by default (in a restricted form that does not allow shell redirection) these are (in a default TeX Live 2021 configuration)

  • bibtex
  • bibtex8
  • extractbb
  • gregorio
  • kpsewhich
  • makeindex
  • repstopdf
  • r-mpost
  • texosquery-jre8

If you do not want to allow even these programs to run, then you can use the option
--no-shell-escape
in all the ways described for --shell-escape below.

To check if the shell-escape mechanism is active, you can use this small document (taken from here), but slightly changed so that it produces output --- log messages are often hidden in some editor/integrated environments):

\documentclass{article}
  \usepackage{shellesc}
  \begin{document}

  \ifcase\ShellEscapeStatus
    No shell escape\or
    Unrestricted shell escape\or
    Restricted shell escape%
  \fi

\end{document}

It will create a document with the current shell escape setting displayed.

Related Question