Compiling features

Building the document

A LaTeX file is typically built by calling the command Build LaTeX project from the Command Palette or from the TeX badge. This command is bind to ctrl+alt+b. If you cannot use ctrl+alt in a keybinding, see the FAQ. The recipe called by this command is defined by latex-workshop.latex.recipe.default.

If you have a multi-file project, see multi-files-projects for more details on how the root file is discovered.

You can define several compiling toolchains to build LaTeX projects using LaTeX recipes and then call the command Build with recipe to choose the appropriate toolchain for actually building the project. Alternatively, you can directly select the appropriate recipe from the TeX badge.

The following settings are helpful to customize how to build a project and how to deal with failures.

Setting key	Description	Default	Type
`latex-workshop.latex.autoBuild.run`	When the extension shall auto build LaTeX project using the default (first) recipe.	`onFileChange`	string
`latex-workshop.latex.recipes`	Sequence of tools to run for building		JSON object
`latex-workshop.latex.tools`	Tools available for building		JSON object
`latex-workshop.latex.magic.args`	Arguments for the `TeX program`		array of strings
`latex-workshop.latex.magic.bib.args`	Arguments for the `BIB program`		array of strings
`latex-workshop.latex.build.forceRecipeUsage`	Force the use of recipes	false	boolean

A progress bar indicates the building progress. It can be customized using the following configuration variables

latex-workshop.progress.location
latex-workshop.progress.runIconType
latex-workshop.progress.barLength
latex-workshop.progress.barStyle

Terminating the current compilation

It is possible to terminate the current compilation by calling Kill LaTeX compiler process from the Command Palette (command latex-workshop.kill) or calling Terminate current compilation from the TeX badge in the Build LaTeX project item.

Auto build LaTeX

Besides manually calling the Build LaTeX Project command to compile a document, you may also let the extension automatically start compiling it upon file change. This can be defined in latex-workshop.latex.autoBuild.run. The recipe called by auto build is defined by latex-workshop.latex.recipe.default.

latex-workshop.latex.autoBuild.run

When to trigger automatic building.

type	default value	possible values
string	`"onFileChange"`	`"never"`,`"onFileChange"`

"never": Disable the auto build feature
"onFileChange": Build the project upon detecting a file change in any of the dependencies. The file can even be modified outside vscode. See here for explanations on what dependencies are and how some of them can be ignored. See the FAQ for how to save without triggering the build when this feature is on. When a file changes, we wait for a delay before triggering the build. This delay is configured by latex-workshop.latex.watch.delay

latex-workshop.latex.autoBuild.interval

The minimal time interval between two consecutive auto builds in milliseconds.

type	default value
integer	`1000`

Cleaning generated files

LaTeX compilation typically generates several auxiliary files. They can be removed by calling Clean up auxiliary files from the Command Palette or from the TeX badge. The associated internal command latex-workshop.clean is bind to ctrl+alt+c. If you cannot use ctrl+alt in a keybinding, see the FAQ.

Setting key	Description	Default	Type
`latex-workshop.latex.autoBuild.cleanAndRetry.enabled`	Enable cleaning and building once more after errors in the build toolchain	`true`	boolean
`latex-workshop.latex.autoClean.run`	Define when LaTeX auxillary files should be deleted.	`"never"`	string
`latex-workshop.latex.clean.fileTypes`	Extensions of files to clean		array of strings
`latex-workshop.latex.clean.subfolder.enabled`	Clean LaTeX auxillary files recursively in sub-folders of `latex-workshop.latex.outDir`	false	boolean

latex-workshop.latex.autoClean.run

type	default value	possible values
string	`"never"`	`"never"`,`"onFailed"`, `"onBuilt"`

"never": Disable the auto cleaning feature
"onFailed": Clean the project upon failed compilation.
"onBuilt": Clean the project upon completing a compilation, whether it is successful or not.

LaTeX recipes

A LaTeX recipe refers to a sequence/array of commands which LaTeX Workshop executes sequentially when building LaTeX projects. It is defined by latex-workshop.latex.recipes. By default, LaTeX Workshop includes two basic recipes defined by the variables latex-workshop.latex.recipes and latex-workshop.latex.tools:

The first one simply relies on the latexmk command
The second one run the following sequence of commands pdflatex → bibtex → pdflatex → pdflatex.

[
  {
    "name": "latexmk 🔃",
    "tools": [
      "latexmk"
    ]
  },
  {
    "name": "pdflatex ➞ bibtex ➞ pdflatex`×2",
    "tools": [
      "pdflatex",
      "bibtex",
      "pdflatex",
      "pdflatex"
    ]
  }
]

and each tool appearing in the tools field is defined latex-workshop.latex.tools. Its default value is given by

[
  {
    "name": "latexmk",
    "command": "latexmk",
    "args": [
      "-synctex=1",
      "-interaction=nonstopmode",
      "-file-line-error",
      "-pdf",
      "-outdir=%OUTDIR%",
      "%DOC%"
    ],
    "env": {}
  },
  {
    "name": "pdflatex",
    "command": "pdflatex",
    "args": [
      "-synctex=1",
      "-interaction=nonstopmode",
      "-file-line-error",
      "%DOC%"
    ],
    "env": {}
  },
  {
    "name": "bibtex",
    "command": "bibtex",
    "args": [
      "%DOCFILE%"
    ],
    "env": {}
  }
]

You can create multiple recipes with different tools. Each recipe is an object in the configuration list, consisting of a name field and a list of tools to be invoked in the recipe.

The tools in recipes can be defined in latex-workshop.latex.tools, in which each command is a tool. Each tool is an object consisting of a name, a command to be spawned, its arguments (args) and some specific environment variables (env). The env entry is a dictionary. Imagine you want to use a texmf subdirectory local to your home project, just write

  "env": {
      "TEXMFHOME": "%DIR%/texmf"
  }

You can also override PATH environment variable.

To include a tool in a recipe, the tool's name should be included in the recipe's tools list.

When building the project, the magic comments in the root file are used if present, otherwise the first recipe is used. You can compile with another recipe by command latex-workshop.recipes. By default latexmk is used. This tool is bundled in most LaTeX distributions, and requires perl to execute. For non-perl users, the following texify toolchain from MikTeX may worth a try:

"latex-workshop.latex.recipes": [{
  "name": "texify",
  "tools": [
    "texify"
  ]
}],
"latex-workshop.latex.tools": [{
  "name": "texify",
  "command": "texify",
  "args": [
    "--synctex",
    "--pdf",
    "--tex-option=\"-interaction=nonstopmode\"",
    "--tex-option=\"-file-line-error\"",
    "%DOC_EXT%"
  ],
    "env": {}
}]

The args and env parameters can contain symbols surrounded by %. These placeholders are replaced on-the-fly.

Placeholders

LaTeX Workshop registers the following placeholders

Placeholder	Replaced by
`%DOC%`	The root file full path without the extension
`%DOC_W32%`	The root file full path without the extension with `\` path separator on Windows
`%DOCFILE%`	The root file name without the extension
`%DOC_EXT%`	The root file full path with the extension
`%DOC_EXT_W32%`	The root file full path with the extension with `\` path separator on Windows
`%DOCFILE_EXT%`	The root file name with the extension
`%DIR%`	The root file directory
`%DIR_W32%`	The root file directory with `\` path separator on Windows
`%TMPDIR%`	A temporary folder for storing ancillary files
`%OUTDIR%`	The output directory configured in `latex-workshop.latex.outDir`
`%OUTDIR_W32%`	The output directory configured in `latex-workshop.latex.outDir` with `\` path separator on Windows

As most LaTeX compiler accepts root file name without extension, %DOC% and %DOCFILE% do not include the filename extension. Meanwhile, the texify tool requires the complete filename with its extension, hence the use of %DOC_EXT% in the configuration of texify.

Most commands accept the use of the / path separator even on Windows and most LaTeX tools even require its use. On the contrary, some Windows commands only work with the \ path separator. So, we propose two versions of the placeholders. All placeholders without the _W32 suffix always use the / path separator even on Windows. All placeholders with the _W32 suffix use the \ path separator on Windows. Note on Linux and Unix systems, placeholders with and without the _W32 suffix are equivalent.

latex-workshop.latex.recipe.default

Define which recipe is used by the Build LaTeX project command.

type	default value	possible values
string	`"first"`	`"first"`,`"lastUsed"`

"first": Use the first recipe defined in latex-workshop.latex.recipes.
"lastUsed": Use the last used recipe by the command LaTeX Workshop: Build with recipe.

latex-workshop.latex.build.forceRecipeUsage

Force the use of the recipe system even when a magic comment defines a TeX command.

type	default value
boolean	`false`

External build command

Versatile though the recipe mechanism described above may be, it may fail to match your needs when building the whole LaTeX project is done by a personal script or a Makefile. For this particular case, we provide an external build command mechanism, which completely bypasses the recipe machinery. Just define your command along with its arguments using the following two configuration variables

latex-workshop.latex.external.build.command

The external command to execute when calling latex-workshop.build.

This is useful when compiling relies on a Makefile or a bespoke script. When defined, it completely bypasses the recipes and root file detection mechanism. The command is launched from the workspace directory.

type	default value
string	`""`

latex-workshop.latex.external.build.args

The arguments of latex-workshop.latex.external.build.command when calling latex-workshop.build

If the rootFile is defined, you can use any of the placeholders defined in the section on LaTeX Recipes.

type	default value
string[]	`[]`

Magic comments

TeX program and options

LaTeX Workshop supports % !TEX program magic comment to specify the compiler program. However, it is advised to use the recipe system instead of magic program to define the building process, since the latter is only implemented for backward compatibility.

For % !TEX program magic comment, its arguments are defined in latex-workshop.latex.magic.args:

"latex-workshop.latex.magic.args": [
  "-synctex=1",
  "-interaction=nonstopmode",
  "-file-line-error",
  "%DOC%"
]

Alternatively, you can directly define the args in the .tex file by using the magic comment % !TEX options, which overrides latex-workshop.latex.magic.args. Note that it must contain the file to proceed. For instance, to reproduce the default behavior, you should use

% !TEX options = -synctex=1 -interaction=nonstopmode -file-line-error "%DOC%"

Suppose there is a line % !TEX program = xelatex in the root file. Upon building the project, LaTeX Workshop will parse the root file and figure out that xelatex should be used.

BIB program and options

When using % !TEX program with bibliographies, a bib compiler must be defined with % !BIB program comment, e.g., % !BIB program = bibtex. Otherwise the extension will only run one-pass compilation with the specified LaTeX compiler. If needed, you can pass extra arguments to the % !BIB program using the latex-workshop.latex.magic.bib.args variable:

"latex-workshop.latex.magic.bib.args": [
  "%DOCFILE%"
]

Alternatively, you can directly define the args in the .tex file by using the magic comment % !BIB options, which overrides latex-workshop.latex.magic.bib.args. Note that it must contain the file to proceed. For instance, to reproduce the default behavior, you should use % !BIB options = "%DOCFILE%".

Catching errors and warnings

The warnings and errors issued by the compiling toolchain are rendered in the Problems Pane. The following settings enable you to customize what you want to get in that panel. If the messages displayed in the panel seem to be wrong, see the FAQ.

The raw compiler logs can be accessed in the Output Pane, choose LaTeX Compiler. The default is to clear the logs before calling every tool of a recipe. If you prefer to keep the logs from all the tools of a recipe, set latex-workshop.latex.build.clearLog.everyRecipeStep.enabled to false.

Settings Details

latex-workshop.message.log.show

Display LaTeX Workshop debug log in output panel.

This property defines whether LaTeX Workshop will output its debug log to the log panel.

type	default value
boolean	`true`

latex-workshop.message.badbox.show

Show badbox information in the problems panel.

type	default value
boolean	`true`

latex-workshop.message.latexlog.exclude

Exclude log messages that matches the given regexp from the problems panel.

type	default value
array of strings	`[]`

latex-workshop.message.information.show

Display information messages in popup notifications.

type	default value
boolean	`false`

latex-workshop.message.warning.show

Display warning messages in popup notifications.

type	default value
boolean	`true`

latex-workshop.message.error.show

Display error messages in popup notifications.

type	default value
boolean	`true`

latex-workshop.message.update.show

Display LaTeX Workshop update message on new versions.

type	default value
boolean	`true`

latex-workshop.latex.build.clearLog.everyRecipeStep.enabled

Clear the LaTeX Compiler logs before every step of a recipe.

Set this property to false to keep the logs of all tools in a recipe.

type	default value
boolean	`true`

latex-workshop.progress.location

Optionally display the compilation progress in a pop-up notification dialogue.

type	default value	Possible values
enum	`"Status Bar"`	`"Status Bar"`, `"Notification Dialogue"`

latex-workshop.progress.runIconType

The style of number to use to indicate the run number"

type	default value
enum	`"Parenthesised"`

The possible values are

"Parenthesised": "⑴ ⑵ ⑶ …",
"Circled": "① ② ③ …",
"Solid Circled": "❶ ❷ ❸ …",
"Full Stop": "⒈ ⒉ ⒊ …"

latex-workshop.progress.barLength

Only applies if latex-workshop.progress.location is set to Status Bar.

The length in characters of the progress bar.

type	default value
number	`15`

latex-workshop.progress.barStyle

Only applies if latex-workshop.progress.location is set to Status Bar.

type	default value
enum	`"Block Shading`

The possible values are

"Block Width": "█████▋░░░ (8 levels per block)",
"Block Shading": "█████▓░░░ (4 levels per block)",
"Block Quadrants": "█████▙░░░ (4 levels per block)",
"none": No bar.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Compile.md

Compile.md

Compiling features

Building the document

Terminating the current compilation

Auto build LaTeX

latex-workshop.latex.autoBuild.run

latex-workshop.latex.autoBuild.interval

Cleaning generated files

latex-workshop.latex.autoClean.run

LaTeX recipes

Placeholders

latex-workshop.latex.recipe.default

latex-workshop.latex.build.forceRecipeUsage

External build command

latex-workshop.latex.external.build.command

latex-workshop.latex.external.build.args

Magic comments

TeX program and options

BIB program and options

Catching errors and warnings

Settings Details

latex-workshop.message.log.show

latex-workshop.message.badbox.show

latex-workshop.message.latexlog.exclude

latex-workshop.message.information.show

latex-workshop.message.warning.show

latex-workshop.message.error.show

latex-workshop.message.update.show

latex-workshop.latex.build.clearLog.everyRecipeStep.enabled

latex-workshop.progress.location

latex-workshop.progress.runIconType

latex-workshop.progress.barLength

latex-workshop.progress.barStyle

Files

Compile.md

Latest commit

History

Compile.md

File metadata and controls

Compiling features

Building the document

Terminating the current compilation

Auto build LaTeX

latex-workshop.latex.autoBuild.run

latex-workshop.latex.autoBuild.interval

Cleaning generated files

latex-workshop.latex.autoClean.run

LaTeX recipes

Placeholders

latex-workshop.latex.recipe.default

latex-workshop.latex.build.forceRecipeUsage

External build command

latex-workshop.latex.external.build.command

latex-workshop.latex.external.build.args

Magic comments

TeX program and options

BIB program and options

Catching errors and warnings

Settings Details

latex-workshop.message.log.show

latex-workshop.message.badbox.show

latex-workshop.message.latexlog.exclude

latex-workshop.message.information.show

latex-workshop.message.warning.show

latex-workshop.message.error.show

latex-workshop.message.update.show

latex-workshop.latex.build.clearLog.everyRecipeStep.enabled

latex-workshop.progress.location

latex-workshop.progress.runIconType

latex-workshop.progress.barLength

latex-workshop.progress.barStyle