Sublime Text (LaTeXTools)

For writing LaTeX in Sublime Text, the standard choice is the LaTeXTools package. Install it from Package Control and you get a build system, \ref/\cite completion, command completion, file-name completion, and two-way jumps with your PDF viewer — all without leaving the editor. This page walks through installing and configuring LaTeXTools, how the build works, configuring it for Japanese, completion, and forward/inverse search via SyncTeX.

What LaTeXTools is

Sublime Text does not typeset TeX itself; the actual compiling is done by a TeX installation on your machine — TeX Live, MacTeX, or MiKTeX. LaTeXTools is the package that bridges the two. While you edit a .tex file it automatically enables build commands, parsing of the log with errors surfaced, context-aware completion, jump-to-definition for \labels and citation keys, and launching/synchronizing your PDF viewer. By itself LaTeXTools produces nothing: it assumes a local TeX distribution and a PDF viewer.

Two external pieces are required. First, a TeX distribution: MacTeX on macOS (the lighter BasicTeX works too, but you must add latexmk separately — see below); MiKTeX or TeX Live on Windows; TeX Live from TUG on Linux. Second, a PDF viewer: to enable forward and inverse search, LaTeXTools assumes a default viewer per platform.

Installation goes through Package Control (the recommended method). If you do not have Package Control yet, install it first; then open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS), choose Package Control: Install Package, and pick LaTeXTools from the list. No restart is needed: open a .tex file, the syntax switches to LaTeX, and the features come alive.

Two things to do afterward. First, prepare a settings file: from the Command Palette run LaTeXTools: Reset user settings to default, or use Preferences | Package Settings | LaTeXTools | Settings – User, to create an editable LaTeXTools.sublime-settings in your User directory (never edit the default file in the plugin folder — it is overwritten on upgrade). Second, verify the setup: LaTeXTools: Check System checks whether the TeX commands and your viewer are reachable from LaTeXTools. When something does not work, this is the first command to run.

Building

Builds run on Sublime Text’s standard key, **Ctrl+B** (Cmd+B on macOS). With one build, the default builder (traditional) does all of the following: it saves the current file, invokes the TeX build command, parses the log and lists errors, warnings, and (if enabled) bad boxes in a panel at the bottom, then opens the PDF viewer and does a forward search to your cursor. Click an error in the panel to jump to the corresponding line.

The key fact is that the **traditional builder runs latexmk under the hood.** Precisely: it invokes latexmk on TeX Live and MacTeX, and texify on MiKTeX. latexmk figures out what changed and reruns the toolchain as many times as needed, handling the repeats until cross-references and the table of contents settle. Its default command line is roughly:

latexmk -cd -f -%E -interaction=nonstopmode -synctex=1

Reading it: -cd changes into the source’s directory before processing; -f keeps going as far as possible even after an error; -interaction=nonstopmode avoids interactive stops; and **-synctex=1** emits the synchronization data the forward/inverse search below needs. %E is a placeholder that LaTeXTools replaces with -pdf (pdfLaTeX), -lualatex, -xelatex, etc. according to the chosen engine — so engine selection amounts to swapping what %E expands to.

The easiest way to choose an engine is a magic comment at the top of the file. Put this on the first line of your .tex and the matching engine is used (without it, pdfLaTeX). In a multi-file project, this line goes in the root (master) file. For TeXShop compatibility, TS-program works in place of program:

%!TEX program = lualatex

Only three values are accepted: pdflatex, lualatex, and xelatex. Likewise, %!TEX options = ... passes options to the engine (e.g. --shell-escape), and %!TEX root = <master> names the root file. Instead of magic comments you may also configure these in your settings file or Sublime project. In the builder_settings block of LaTeXTools.sublime-settings you can adjust program (the engine), options, command, and env (environment variables):

{
  "builder_settings": {
    "program": "lualatex",
    "options": ["--shell-escape"]
  }
}

Another essential is the **texpath** setting — the PATH used to find the LaTeX commands when invoking latexmk and friends. On macOS especially, a Sublime Text launched from the GUI has a different PATH than your shell, so an incorrect value fails with “command not found.” The rule: **texpath must include $PATH** (your own paths first, then $PATH). A typical macOS value is "/Library/TeX/texbin:$PATH"; on Windows, something like "C:\\texlive\\2026\\bin\\windows;$PATH", adjusted to your install. On Windows, also set distro to "texlive" or "miktex" to match your distribution.

If traditional is not enough, the builder setting lets you switch to basic (a minimal builder running the engine plus bibtex/biber) or script (an advanced builder where you write your own command sequence in script_commands). Note that --output-directory, --aux-directory, and --jobname work only with latexmk (the traditional builder on OS X/Linux), basic, or script — they are ignored by MiKTeX’s texify.

Configuring for Japanese

Here is where Japanese users often stumble. %!TEX program accepts only pdflatex, lualatex, and xelatex — you **cannot name uplatex or platex directly**. If you typeset Japanese with LuaLaTeX it is simple: write %!TEX program = lualatex and use a luatexja/ltjsclasses-family class.

On the other hand, to use upLaTeX + dvipdfmx — the classic Japanese-paper combination in the sciences, which builds a DVI and then converts it to PDF — the cleanest approach is to **let .latexmkrc choose the engine.** Since the traditional builder calls latexmk under the hood, placing a .latexmkrc in the project directory (or your home directory) switches the toolchain to Japanese processing with almost no change to LaTeXTools’ own settings. Here is an upLaTeX + dvipdfmx example:

$latex = 'uplatex -synctex=1 -interaction=nonstopmode -file-line-error %O %S';
$bibtex = 'upbibtex %O %B';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';
$makeindex = 'upmendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;
$max_repeat = 5;

The key points: assign uplatex to $latex and dvipdfmx to $dvipdf, then set $pdf_mode = 3 to choose the “build a DVI, then convert to PDF with dvipdfmx” path. Passing **-synctex=1** to $latex as well carries the SyncTeX data through to the PDF even via DVI, so the search below works. On the LaTeXTools side, it is safest not to write a %!TEX program line (doing so would select the pdfLaTeX %E).

To be more explicit, you can name latexmk directly via the command key in builder_settings. Writing "command": "latexmk" (keeping options like -pdfdvi in .latexmkrc) guarantees the Japanese-configured latexmk runs. Customizing command does disable engine auto-selection via %!TEX program, but in a setup that fixes the toolchain in .latexmkrc — as Japanese workflows do — that is no loss.

Completion

LaTeXTools’ completion falls into three families: command completion, **\ref/\cite completion, and file/package-name completion (the Fill Helper). First, command completion. LaTeXTools ships the TeXStudio-derived completion word lists (CWL**) and shows a popup of candidates as soon as you start a command with \. Type \te, for instance, and \textit and the like appear. The behavior is controlled by the command_completion setting — prefixed (default; only when the word starts with \), always, or never. Candidates for the packages loaded in your document are added automatically via cwl_autoload (on by default). Enable env_auto_trigger and environment names are completed when you type \begin{/\end{ as well.

Next, reference and citation completion — one of LaTeXTools’ highlights. By default, the instant you type \ref{ or \cite{, a quick panel (a candidate list) appears at the top of the screen: for \ref{, all \labels in the document; for \cite{, all entries in the bibliographies you reference via \bibliography{} or biblatex’s \addbibresource{}. Type a few characters to fuzzy-filter, select, and press Enter, and the whole command is inserted, e.g. \ref{my-label}. Type a comma just before the closing brace, as in \cite{paper1,, and you pick the second and later keys of a multiple citation the same way.

Two caveats. First, LaTeXTools collects candidates from the saved file; if a label or key you just added does not show, save first. Second, only **external .bib files** are supported — \bibitems written inline are not. If this auto-trigger feels intrusive, a toggle or setting turns it off. To invoke it manually, press **Ctrl+l, x** (Cmd+l, x on macOS) or **Ctrl+l, Ctrl+f** right after \ref{ and the like (the same key as the Fill Helper below, which also works for \ref/\cite). Reference and citation commands from cleveref, fancyref, varioref, natbib, and biblatex are recognized too.

The third is the Fill Helper. Type \usepackage{, \include{, \input{, \includegraphics{, and the like, and it offers a list of available packages or files: installed packages for \usepackage{, and files in the current directory for the file commands (filtered to image files for \includegraphics). This too is shown automatically by default, or invoked manually with Ctrl+l, Ctrl+f. The one bit of preparation is package completion: run LaTeXTools: Build cache for LaTeX packages from the Command Palette once to build the package cache.

SyncTeX (forward/inverse search)

SyncTeX records the correspondence between source lines and positions in the PDF, enabling forward search — jumping from your editing position to the PDF — and inverse search — going from a place in the PDF back to the source line. LaTeXTools’ default build command includes -synctex=1, so an ordinary Ctrl+B build emits the synchronization data (.synctex.gz) for you. For Japanese via DVI, the point is to pass -synctex=1 to $latex in .latexmkrc as well, as noted above. The background to how this works is covered on the SyncTeX page.

Forward search runs from a LaTeXTools key. While editing a .tex, press **Ctrl+l, j** (Cmd+l, j on macOS) and the PDF page matching your cursor is shown. A forward search also runs automatically right after a build, so Ctrl+B alone opens the right spot. (Ctrl+l is normally “expand selection to line,” but for .tex files with LaTeXTools active it is remapped to Ctrl+l, Ctrl+l, freeing Ctrl+l as the prefix for the plugin’s commands.) To merely open the PDF without syncing, use Ctrl+l, v.

Inverse search (PDF → source) needs the viewer to call back into Sublime Text. The click gesture differs per viewer:

• Skim (macOS) — **Cmd+Shift+click** in the PDF.
• SumatraPDF (Windows) — double-click in the PDF.
• Evince (Linux) — **Ctrl+left-click** in the PDF (Okular: Shift+left-click; Zathura: Ctrl+left-click).

On macOS — Skim, enable inverse search in Skim’s preferences: open the Preferences → Sync tab, uncheck “Check for file changes,” and simply choose the “Sublime Text” preset. On older Skim builds without the preset, choose “Custom” and set Command to the absolute path of subl (/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl) and Arguments to "%file":%line.

On Windows — SumatraPDF, first add SumatraPDF to your PATH so LaTeXTools can find it easily. The inverse-search settings UI appears only when you open a PDF that has synchronization data (.synctex.gz), so build once with Ctrl+B, open the PDF in Sumatra, and under Settings → Options register the inverse-search command line below (adjust the ST path to your install):

"C:\\Program Files\\Sublime Text\\sublime_text.exe" "%f:%l"

With a viewer that lacks support, the forward-search key (Ctrl+l, j) simply behaves like “open the PDF.” When inverse search misbehaves, check in this order: whether the build ran with -synctex=1, whether the viewer’s preset/command is correct, and — via LaTeXTools: Check System — whether sublime_executable (the location of subl) is visible.