38

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.

6
  • 1
    +1 Great effort! May 27, 2021 at 13:22
  • can you add Texworks in the list
    – rpapa
    May 28, 2021 at 7:06
  • @rpapa I don't have Texworks installed, so I don't know how it works there - maybe you can add an answer for Texworks?
    – Marijn
    May 28, 2021 at 7:07
  • 1
    can someone add Texpad?
    – Michelle
    Dec 12, 2021 at 22:11
  • 1
    vscode would be good
    – safetyduck
    Mar 1, 2022 at 11:36

13 Answers 13

22

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.

0
12

AUCTeX (Emacs)

Custmize variable TeX-command-extra-options to have value " -shell-escape ":

  1. Enter customization typing (in Emacs jargon) M-x customize-option RET TeX-command-extra-options RET (that is, Alt+X, then customize-option, ENTER, TeX-command-extra-options, ENTER)

  2. In the edit box, type -shell-escape , ensuring spaces before and after -shell-escape.

  3. Then click on Apply and Save to make change permanent.

Emacs screenshot

To set this on a per-file basis, use a file-local variable to set TeX-command-extra-options. You can set this by M-x add-file-local-variable RET TeX-command-extra-options RET "-shell-escape" RET.

This adds

% Local Variables:
% TeX-command-extra-options: "-shell-escape"
% End:

to the bottom of the file, telling emacs to use the value "-shell-escape" for this file.

You can check if a general variable can be set file-locally by M-x describe-variable RET and then the variable name RET and check to see if it says something like "automatically becomes buffer local when set".

3
  • Thanks for the answer. I'm not familiar with AUCTeX, is this per document or a general setting? Is it possible to use different shortcuts to compile with and without shell escape?
    – Marijn
    May 27, 2021 at 13:53
  • This is a general setting. I will search for a per document solution and edit post to include that. May 27, 2021 at 14:02
  • You can use file local variables. The M-x describe-variable for TeX-command-extra-options says Automatically becomes buffer-local when set, so you can use a file-local. To set it for a specific file, say M-x add-file-local-variable, then TeX-command-extra-options, and then "-shell-escape". This will add the following text to the bottom of your file: % Local Variables:\n % TeX-command-extra-options: "-shell-escape" \n % End: Whenever that file has focus, it will set TeX-command-extra-options accordingly, using shell escape.
    – Riley
    Mar 19, 2023 at 2:37
9

Arara

Arara uses 'magic comments' at the top of the .tex file to determine the options. For shell escape you need to add the option shell: true or equivalently shell: yes. The options are specified between curly braces and separated by commas. Examples:

% arara: pdflatex: { shell: true }
% arara: xelatex: { synctex: 1, shell: yes }
% arara: lualatex: { shell: true, interaction: nonstopmode }
8

Overleaf

Overleaf has shell escape enabled by default. However, it only works when your document is in the root folder of your Overleaf project.

2
  • Is it the same for ShareLatex? I get the error: Package svg Error: File 'name_file_svg-tex.pdf_tex' is missing
    – Wallflower
    Jun 3, 2023 at 14:06
  • @Wallflower ShareLaTeX has been incorporated into Overleaf, so it should be the same, i.e., it should work without changing any settings. Maybe there is a problem with the SVG that causes the conversion to fail. You can check the errors/warnings list for messages (the icon labelled "logs and output files" next to the Compile button). At the bottom of that list there is also a section "Raw logs" that contains the original log file which may have more information.
    – Marijn
    Jun 3, 2023 at 14:18
8

Latexmk

To enable shell escape in Latexmk you need to add the -shell-escape option to the Latexmk call, as follows:

latexmk -shell-escape yourfile.tex
6

Terminal/Command Prompt

To enable shell escape when you use the terminal (Linux/Mac) or Command Prompt (Windows) to compile, you should add the -shell-escape flag to the command, in between the compiler name and the filename. Examples:

pdflatex -shell-escape yourfile.tex
xelatex -shell-escape yourfile.tex
lualatex -shell-escape yourfile.tex

You generally need to add the flag every time you run the compiler. Do not add the flag to other programs such as bibtex, biber, makeglossaries etc.

6

Vim + vimtex

The vimtex plugin is highly configurable in terms of which command it uses under the hood to compile LaTeX sources. So the steps needed to add -shell-escape will depend on the specific one you are using.

In general, vimtex admits a magic comment in the form of

 %! TEX program = my-program

but in this case, my-program is a key to an internal table where the real commands or options for the commands are kept. Notice that if you change this directive you have to reload the plugin (\lx by default) to make it active.

vim + vimtex + latexmk

By default, there are no keys that enable the usage of -shell-escape directly from the source file. The recommended way is to add a latexmkrc file in the root directory of your project with the content:

$pdflatex = 'pdflatex --shell-escape %O %S';

(or lualatex or xelatex or...).


If somebody uses vimtex with latexrun or other configurations, please add/edit this entry!

1
6

Texmaker

To enable shell escape in Texmaker, open the menu OptionsConfigure Temaker (or press Ctrl+,), add -shell-escape to the commands of interest, and then click OK. For example:

Configure Texmaker panel

The configuration changes apply to all documents and are restored at the next execution.

Alternatively, to define a separate compilation command with shell escape enabled, open the menu UserUser CommandsEdit User Commands, select an empty command, and add the compilation command of your choice with the option -shell-escape. For example:

Edit user commands panel

You can then run the command either from the menu UserUser Commands or by pressing Alt+Shift+Fn, where n is the number of the defined user command.

5

TeXstudio

To enable shell escape globally (for all documents), you can go under menu OptionsConfigure TeXstudioCommands and then add -shell-escape after appropriate commands.

For example, to enable shell escape for LuaLaTeX, the command in its row should be:

lualatex.exe -synctex=1 -interaction=nonstopmode -shell-escape %.tex

TeXstudio LuaLaTeX compiler dispatch setting

To enable shell escape on a per-document basis, a "magic comment" can be added to the root document. For PDFLaTeX, the comment is:

% !TeX TXS-program:compile = txs:///pdflatex/[-shell-escape]

For LuaLaTeX:

% !TeX TXS-program:compile = txs:///lualatex/[-shell-escape]

Et cetera.

Note that the first time the document is compiled with the comment inserted, TeXstudio will ask for user permission to execute the command. It may also add a !TeX document-id = ... line to the document preamble, allowing it to remember the setting. The software will re-request permission to run the command any time the command is modified in any way.

6
  • Is nonstopmode necessary for TeXstudio, or can you also use other modes? If other modes are possible, maybe this setting can be removed from the example (because nonstopmode hides errors, which is bad)?
    – Marijn
    May 28, 2021 at 10:58
  • And more in general (see also the updated note on the question): could you 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? Thanks!
    – Marijn
    May 28, 2021 at 11:04
  • 1
    @Marijn: -synctex=1 -interaction=nonstopmode are the TeXstudio default compiler flags. If these flags are omitted from the example, I suspect a lot of less-technically-inclined users will inadvertently wipe them out by copy-pasting and then wonder why their compiler and viewer work differently.
    – COTO
    May 28, 2021 at 15:10
  • Is there a way to enable the shell escape in Overleaf please?
    – Wallflower
    Jun 3, 2023 at 14:01
  • @Wallflower , supposedly, Overleaf does this automatically in some cases. But I am not sure if your case is also covered. overleaf.com/learn/latex/…
    – Fato39
    Jun 6, 2023 at 16:23
3

Vim + vimtex

To elaborate on Rmano's answer, here's exactly you need to have vimetex use pdflatex -shell-escape when building select documents within vim (correct as of Jan 2023):

  1. A magic comment %! TEX program = pdf_escaped at the very top of the document (.tex)
  2. A dictionary g:vimtex_compiler_latexmk_engines inside your .vimrc,
let g:vimtex_compiler_latexmk_engines = {
    \ '_'           : '-pdf',
    \ 'pdf_escaped' : '-pdf -pdflatex="pdflatex -shell-escape %O %S"',
\}

Here default engine '_' is defined via -pdf as pdflatex (without any options), and the engine for any files with TEX program set as in 1. to pdflatex with the shell-escape option. Remember to reload the plugin and source your .vimrc after making changes 1. and 2. respectively (closing and opening vim is sufficient for both). The keybinding \li is useful to inspect the current build command and options.

If you wish to use -shell-escape for everything, then you can either set it in your default '_' above or simply pass the option directly to latexmk by specifying a different dictionary,

let g:vimtex_compiler_latexmk = {
                    \ 'options': [
                    \ '-shell-escape',
                    \ ],
            \}

in your .vimrc.

2

Visual Studio Code + LaTeX Workshop

In Visual Studio Code you can create a shortcut, a so called "recipe", with the LaTeX Workshop extension which lets you compile the document with a single click in the extension's interface.

Go to the file settings.json by opening your Command Palette (Ctrl+Shift+P) and choosing "Preferences: Open Settings (JSON)". You will need to add a recipe and a "tool" which can be used by the recipe as many times as needed. Since there will already be a few recipes and other settings in there, don't forget to separate them with commas. For xelatex and lualatex just replace "command": "pdflatex" with the appropriate one.

{
    "latex-workshop.latex.recipes": [
        {
            "name": "pdflatex-shell-escape-recipe",
            "tools": [
                "pdflatex-shell-escape"
            ]
        }
    ],
    "latex-workshop.latex.tools": [
        {
            "name": "pdflatex-shell-escape",
            "command": "pdflatex",
            "args": [
                "--shell-escape",
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOC%"
            ]
        }
    ]
}

1

AUCTEX

I am an AUCTeX User. I use this user function

  (defun TeX-command-toggle-shell-escape ()
        (interactive)
        (setq TeX-command-extra-options
              (cond ((string-match-p "\\_<--shell-escape\\_>" TeX-command-extra-options )
                     (replace-regexp-in-string "\\_<--shell-escape\\_>" "" TeX-command-extra-options))
                    ((string-empty-p TeX-command-extra-options)"--shell-escape")
                    (t(format "--shell-escape %s" TeX-command-extra-options))))
        (message "TeX-command-extra-options : `%s'" TeX-command-extra-options))

and I have bound this function to "C-c C-t C-x". I find it very convenient.

1
  • 1
    The simple solution is M-x customize-variable RET TeX-command-extra-options RET and add -shell-escape.
    – mcp
    Sep 7, 2022 at 23:01
1

latexrun

latexrun defaults to pdflatex so we can add --shell-escape using the --latex-args flag in a similar way to the Terminal/Command Prompt answer.

./latexrun --latex-args="--shell-escape" test.tex

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .