Skip to content

FAQ

Jump to bottom
James Yu edited this page Apr 19, 2024 · 144 revisions

FAQ and common issues

Known incompatible Extensions

The following extensions are known to cause issues when active at the same time as LaTeX-Workshop

Using LaTeX Workshop with WSL

Starting with 1.35.0, VS Code supports WSL through Remote - WSL. LaTeX Workshop works well with the extension.

See https://github.com/microsoft/WSL/issues/4739 for more information about the issue. Alternatively, you can set latex-workshop.saveWithoutBuilding: onSave to only trigger a build upon saving a file as it does not require file watchers to work.

Problems with Snap and Flatpak versions of VS Code

These versions are sandboxed and are known to cause problems (e.g. here). We strongly recommend not using the snap and flatpack versions of VS Code. We strongly recommend using other installation options, like the .deb package for Debian/Ubuntu based distributions.

The PDF viewer is blank or has graphical glitches

If the PDF viewer is blank or has graphical glitches, please try restarting VS Code with the option --disable-gpu. See the official document, realted issue, and another issue.

Cygwin is not supported

LaTeX Workshop does not support TeX Live installed through Cygwin. Please install TeX Live and other TeX distributions independently of Cygwin.

code-server is not supported

LaTeX Workshop does not support code-server.

Gitpod is not supported

LaTeX Workshop does not support Gitpod.

openvscode-server is not supported

LaTeX Workshop does not support openvscode-server.

Eclipse Theia is not supported

LaTeX Workshop does not support Eclipse Theia.

Onivim 2 is not supported

LaTeX Workshop does not support Onivim 2.

The github.dev web-based editor is not supported

LaTeX Workshop does not support the github.dev web-based editor and vscode.dev.

VSCodium is not officially supported

VSCodium is not officially supported due to the maintenance burden. We do not help to resolve issues related to VSCodium.

Code OSS on Arch Linux and Manjaro is not officially supported

Open-source builds of Visual Studio Code on Arch Linux and Manjaro are not officially supported due to the maintenance burden. We do not help to resolve issues related to those builds. Please use the official binary distribution.

Visual Studio Live Share is not supported

Visual Studio Live Share is not supported.

LaTeX Utilities is not supported

LaTeX Utilities is not supported.

The directory ~/node_modules/ may cause errors

The directory ~/node_modules/ in the home directory may cause errors on Mac and Linux. The modules in the directory might be unintentionally loaded by VSCode because of the default behavior of node.js, which would cause errors such as Extension host terminated unexpectedly. We recommend moving the directory ~/node_modules/ to ~/npm/node_modules/.

LaTeX Workshop doesn't work with a multi-file project

If you cannot build a multi file LaTeX project from a subfile, it means that the root file is not detected properly. See the Multi file projects section for details on how the root file is discovered. Note that you must open the directory (or one of its antecedents) containing all the project files in vscode for this mechanism to work.

If you are directly calling LaTeX commands, pdflatex, and others in your recipe, please try passing -recorder to the LaTeX command in your recipe.

The Problem Pane displays wrong messages

Please make sure at first that you call LaTeX compilers with an option -file-line-error.

LaTeX compilers usually produce hard wrapped log messages, which makes them really hard to parse. To hopefully deal with complex log messages, we have decided to rely on non hard wrapped log messages. This can be achieved either

  • by setting the environment variable max_print_line. This is automatically done within the extension and works for the TeXLive distribution.
  • by adding the --max-print-line option to the compilers. This is automatically done within the extension and works for the MiKTeX distribution. Unfortunately, some compilers such as lualatex do not understand this option and may therefore fail. To disable the automatic addition of this option, set latex-workshop.latex.option.maxPrintLine.enabled to false.

Note that when log messages are hard wrapped, the Problems Pane is likely to be messed up.

Encoding issues with file names in the Problem Pane

If you experience encoding issues with file names displayed in the Problem Pane, you can try to set latex-workshop.message.convertFilenameEncoding to false.

I cannot use ctrl+alt in a shortcut

The default shortcuts for commands related to build and view use the modifiers ctrl+alt. On some keyboard layouts, ctrl+alt is used to emulate AltrGr, which makes these shortcuts unusable. Alternatively, you can use ctrl+l, alt+letter instead of ctrl+alt+letter by setting latex-workshop.bind.altKeymap.enabled to true.

Auto build does not work sometimes

Please try setting latex-workshop.latex.autoBuild.run to onSave.

Reload vscode to make any change in this configuration effective.

Saving a .cls file does not trigger auto build

You have to compile your project with latexmk or manually pass -recorder to your LaTeX compiler to produce a .fls file. Then, LaTeX Workshop will use it to compute the exact list of included files. See Compile.

Disable automatic build on save

Set the configuration variable latex-workshop.latex.autoBuild.run to "never".

I use build on save but I occasionally want to save without building

When latex-workshop.latex.autoBuild.run is set to onSave, building is triggered every time a file is saved inside VSCode. If you want to save a file without building it, you can use the Save without Building command from the Command Palette. A keybinding can be associated to the internal command latex-workshop.saveWithoutBuilding to access this feature more easily.

Auto build LaTeX results in always twice or infinite loop

There is a possibility that LaTeX Workshop detects changes on files by build scripts during the build process and starts a new build process. That results in unintended multiple build processes. See #2237 and #2487. In that case, please change the setting latex-workshop.latex.autoBuild.run to "onSave".

With TikZ, builds result in an infinite loop

When builds result in an infinite loop with TikZ or other advanced packages, please replace -interaction=nonstopmode with -halt-on-error in your recipe.

Large bibtex files are ignored

Bibtex files listed in a project are parsed for citation completion. This may induce significant slow down with large bibtex files. You can configure the maximum size of bibtex files parsed by the extension with latex-workshop.bibtex.maxFileSize.

Path containing Chinese or ~ characters

On some platforms, when the path of a TeX file contains Chinese characters, other non-ASCII characters, or a tilde "~", the compilation does not work well. In such cases, please use %DOCFILE% instead of %DOC% in your recipes. See also LaTeX recipes. Note that using relative paths instead of absolute ones may lead to other issues, see the following issues for a discussion on this: 1070 and 1137.

On some platforms, synctex does not work well with the path containing non-ASCII characters either. In such cases, please use a built-in synctex functionality. See Viewing & Synctex.

IME doesn't work well with LaTeX Workshop

Please try setting latex-workshop.bind.enter.key to false.

The LaTeX sidebar keeps reopening

If you like to work with no sidebar in Visual Studio Code and yet the LaTeX sidebar keeps showing up each time you switch focus from a non TeX file to a TeX file, you need to set latex-workshop.view.autoFocus.enabled to false.

Spell check

LTeX is a great tool for checking spelling, grammar and style in many languages. If you only need spell checking, Code Spellchecker does a great job, too.

I cannot nest snippets

Nesting snippets requires to have intellisense automatically triggered inside snippets. This can be achieved by setting editor.suggest.snippetsPreventQuickSuggestions to false.

How to pass -shell-escape to latexmk

Some packages such as minted requires LaTeX compilers to use the -shell-escape flag. Passing this flag can be achieved in several different ways.

  1. Modify the section of latex-workshop.latex.tools related to latexmk in the following way

    "name": "latexmk",
"command": "latexmk",
"args": [
    "-shell-escape",
    "-synctex=1",
    "-interaction=nonstopmode",
    "-file-line-error",
    "-pdf",
    "-outdir=%OUTDIR%",
    "%DOC%"
]

  2. Directly specify -shell-escape in the compiler flag of latexmk. Modify the section of latex-workshop.latex.tools related to latexmk in the following way

    "name": "latexmk",
"command": "latexmk",
"args": [
    "-synctex=1",
    "-interaction=nonstopmode",
    "-file-line-error",
    "-pdf",
    "-pdflatex=pdflatex -shell-escape %O %S",
    "-outdir=%OUTDIR%",
    "%DOC%"
]

  3. Create a .latexmkrc config file (in your home directory or in the working directory) containing at least

    $pdflatex='pdflatex -shell-escape';

LaTeX-Workshop shadows vscode's default keybindings

LaTeX-Workshop uses Ctrl+L as the first key of many keybindings

Since vscode 1.32.0, Ctrl+L has been set to expandLineSelection. We define a new keybinding for expandLineSelection: Ctrl+L, Ctrl+L.

LaTeX-Workshop uses Ctrl+M for fonts keybindings

vscode sets Ctrl+M to editor.action.toggleTabFocusMode. We define a new keybinding for editor.action.toggleTabFocusMode: Ctrl+L, Ctrl+M.

Syntax Highlighting does not work for most elements

Please change VS Code theme you are using. For example, Visual Studio Dark and Visual Studio Light do not work with LaTeX Workshop.

Install an older version of LaTeX Workshop

You can install older versions of LaTeX Workshop by right-clicking it in the extension panel of VS Code and selecting Install Another Version.

Downgrade VS Code to an older version

You can downgrade VS Code to an older version with binaries in each release note.

Customizing a Color Theme

To customize a color theme, you can refer to the official documentation. The following is an example to make fonts black in math environment. Writing it in your settings.json, you can enable that. To find an appropriate scope for each element in a TeX document, you can use the scope inspector of VS Code. Please refer to this document.

    "editor.tokenColorCustomizations": {
        "textMateRules": [
            {
                "scope": [
                    "support.class.math.block.environment.latex",
                ],
                "settings": {
                    "foreground": "#000000"
                }
            }
        ]
    }

Move the structure view and others to other places

You can move the structure view and others with dragging and dropping. See the release note. You can also hide the views in your right-click context menu. See the document.

Overriding snippets

You can override some snippets provided by the extension by using the latex-workshop.intellisense.command.user configuration variable. Since VS Code v1.52, you can hide snippets. See the release note.

Where can I find the definitions of the placeholders

Compile#placeholders

Autocompletion for \includegraphics seems incomplete

Autocompletion for includegraphics takes into account the paths listed by the \graphicspath command if any. In such a case, we only list the files located under these directories. See also the configuration variables referenced here

Environment variables in .bashrc don't take effect with VS Code Remote

Use .bash_profile or .profile instead of .bashrc. See superuser, stackoverflow, and the reference manual.

After editing these files, you have to kill vscode-server on the remote host and restart it. Select Remote-SSH: Kill VS Code Server on Host... from the Command Palette (F1).

Environment variables in .zshrc don't take effect with VS Code Remote

Use .zshenv or .zprofile instead of .zshrc. See stackexchange.

After editing these files, you have to kill vscode-server on the remote host and restart it. Select Remote-SSH: Kill VS Code Server on Host... from the Command Palette (F1).

You cannot use a tilde ~ in PATH

You can not use a tilde ~ in the environment variable PATH as an abbreviation of your home directory.

terminal.integrated.shellArgs.linux doesn't take effect

The setting terminal.integrated.shellArgs.linux is not related to the environment variable on the extension host. You cannot set PATH for LaTeX Workshop through the setting.

What kinds of LaTeX commands does Hover Preview support?

We implement Hover Preview with MathJax. Please see the following for LaTeX commands supported by MathJax:

You have to load MathJax extensions for some LaTeX commands. See the setting. Notice that MathJax does not support other advanced LaTeX packages.

Hover Preview fails to render math equation with errors

Please try setting latex-workshop.hover.preview.newcommand.parseTeXFile.enabled to false.

The file settings.json doesn't have default values of settings

Enter a configuration id you want to configurate, e.g. "latex-workshop.latex.recipes", then trigger auto-completion of VS Code. Related issues, #127819, #134908.

Why don't you integrate the recipe system with the VS Code task feature?

The VS Code task feature doesn't fit our needs.

How to prevent the internal PDF viewer from opening when selecting a PDF file in the explorer?

Set "workbench.list.openMode": "doubleClick" in settings.json. See the document.

Can I define my own listing environment?

Any environment matching [a-zA-Z]*code is considered as a code / listing environment. This is the best we can offer as the textmate engine used for colorization does not allow user configuration.

Why PDF refresh and SyncTeX stop functioning after my computer slept and waked?

We have some logic trying to reconnect PDF viewer back with the extension. However, it may not work for some particular computer-network combinations. The most reliable solution is to close and reopen the PDF viewer.

Want to contribute to this Wiki?

Fork it and send a pull request.

Table of Contents

Clone this wiki locally