Skip to content

Use LaTeX in VS Code

Compiling LaTeX locally gives you more control, works offline and fits naturally with Git.

The basic local setup has three parts:

  1. a LaTeX distribution that contains the compiler and packages;
  2. Visual Studio Code; and
  3. the LaTeX Workshop extension.

1. Install a LaTeX distribution

Use the official instructions for your operating system.

Windows

Install either MiKTeX or TeX Live.

MiKTeX is approachable and can install missing packages as required. TeX Live is widely used across platforms and installs a more complete toolchain when you choose a full installation.

macOS

Install MacTeX, which is the standard TeX Live distribution packaged for macOS.

MacTeX is large. A smaller BasicTeX installation exists, but beginners may then need to install missing packages manually. If storage is not a serious problem, the complete installation is usually less frustrating.

Ubuntu and other Linux distributions

Use TeX Live. Your Linux distribution may provide TeX Live through its package manager, while the TeX Users Group also publishes its own installer.

Choose one installation route and follow its official instructions. Do not combine several partial TeX installations unless you understand how their paths and package managers interact.

2. Install VS Code and LaTeX Workshop

Install VS Code, then add the LaTeX Workshop extension from the VS Code Marketplace.

Open the folder containing the whole LaTeX project, not only main.tex. The extension needs to see the template, bibliography, figures and any included section files.

Open the root .tex file and run the LaTeX Workshop build command. If the distribution is installed correctly, the project should compile and the PDF preview should open inside VS Code.

Tip

Compile an untouched template before changing anything. If the clean template fails, fix the environment first. If it only fails after your edits, the problem is probably in the edits.

3. Keep the template's build system

Most projects can be built using latexmk, which automatically runs LaTeX and the required bibliography steps enough times to resolve references.

Some templates require a particular compiler or bibliography backend, such as:

  • pdfLaTeX;
  • XeLaTeX;
  • LuaLaTeX;
  • BibTeX; or
  • Biber.

Read the template documentation before changing the LaTeX Workshop recipe. If the project already builds on Overleaf, check its compiler setting and reproduce that locally.

4. Put the project in Git

LaTeX source works extremely well with Git because most of the important files are plain text.

Commit:

  • .tex source files;
  • the .bib bibliography;
  • figures and diagrams required to build the paper;
  • custom class and style files supplied by the template; and
  • any scripts used to generate results or figures.

Ignore temporary build files such as .aux, .log, .fls, .fdb_latexmk and .synctex.gz.

5. Connect Zotero through Better BibTeX

For a local project, I recommend using Zotero with the Better BibTeX extension:

  1. create a Zotero collection for the paper;
  2. export the collection using Better BibTeX;
  3. enable Keep updated;
  4. save it as something clear, such as references.bib; and
  5. keep that file inside the LaTeX project.

When the Zotero collection changes, Better BibTeX updates the exported file. LaTeX Workshop then uses the new bibliography the next time the document is built.

Make Zotero the source of truth for reference metadata. If you correct a title, author name or DOI directly in the .bib file, an automatic export may overwrite the correction later.

6. Use one project folder

A sensible structure is:

paper/
├── main.tex
├── references.bib
├── sections/
├── figures/
├── tables/
├── scripts/
└── README.md

The README should record:

  • the required LaTeX distribution or compiler;
  • how to build the document;
  • where figures and results come from;
  • any non-standard packages; and
  • the venue and template version.