SyncTeX (forward/inverse search)

SyncTeX is the machinery that lets you jump in both directions between a spot in your .tex source and the matching spot in the finished PDF. Put your cursor on a paragraph and the viewer scrolls to it; click a word in the PDF and the editor jumps to that source line. When you are proofreading a long document it is indispensable. This page explains how SyncTeX works in general; the per-editor steps live on each editor’s own page.

What SyncTeX is

Because TeX processes the whole manuscript at once to make a PDF, the link between an output line and the place in the source it came from is normally lost. SyncTeX (Synchronize TeXnology) is the technique that preserves that correspondence. It was created by Jérôme Laurens and is now built into the major engines shipped with TeX Live and MiKTeX.

It works in two directions. Going from the source to the PDF is forward search (also called direct synchronization); going from the PDF back to the source is inverse search (or reverse / backward search). Both are a cooperation between your editor and your PDF viewer: the editor asks “show me the output for this line and column,” or “which source position does this PDF coordinate map to,” and the viewer or a helper answers.

Forward and inverse search

Forward search (source → PDF) answers the question you ask while writing: “where will the spot I’m editing end up on the page?” Place the cursor in the editor, press the forward-search key (or a menu item such as “Go to PDF”), and the viewer scrolls to the right page and briefly highlights the matching place.

Inverse search (PDF → source) is the reverse, and it shines while proofreading. Reading the PDF and you spot something to fix? Click that spot (usually with a modifier key) and your editor comes to the front with the cursor on the matching line. The point is that you never have to hunt through a long source for the place to edit.

Under the hood, the command-line tool synctex (shipped with SyncTeX) does the brokering. Forward search corresponds to the subcommand synctex view, inverse search to synctex edit; editors and viewers either call these or implement the equivalent themselves. You normally never see them, but running the two by hand is a handy way to isolate a problem.

The `.synctex.gz` file, and turning it on

This correspondence is recorded in a **.synctex.gz file that the engine writes at compile time. Inside is a map — zlib-compressed — that pairs source file, line, and column with a PDF page and the coordinates of a rectangle (a box) on it**. It sits beside the PDF, with the same base name and in the same folder (main.tex → main.synctex.gz). Neither forward nor inverse search works until this file exists.

To generate it, pass **-synctex=1** when you compile (LuaTeX uses the long form --synctex=1). By hand it looks like this. You need it on every build, so in practice you leave it set once in your editor or build tool.

pdflatex -synctex=1 main.tex
xelatex  -synctex=1 main.tex
lualatex --synctex=1 main.tex

The value is read as bits. **1** gives the gzipped .synctex.gz; **-1** gives a plain, uncompressed .synctex (handy when you want to peek inside or debug). Instead of the command line, you can also switch it on from the top of the source with the TeX primitive \synctex=1.

Build tools are no different. With latexmk, put -synctex=1 into the compile command in your .latexmkrc. Combined with continuous preview (-pvc), every save triggers a recompile and a preview refresh, so forward and inverse search always act on an up-to-date .synctex.gz.

$pdf_mode = 1;
$pdflatex = 'pdflatex -synctex=1 -interaction=nonstopmode %O %S';
# clean up the SyncTeX file too
@generated_exts = (@generated_exts, 'synctex.gz');

Engines, and the DVI route (pLaTeX / upLaTeX)

The engines that emit PDF directly — pdfTeX, XeTeX, and LuaTeX — all understand -synctex and write the .synctex.gz themselves; the same goes for pdfLaTeX, XeLaTeX, and LuaLaTeX. So far, so simple.

The mainstay for Japanese, pLaTeX / upLaTeX, is a two-step pipeline: it first emits a DVI file, which dvipdfmx then turns into PDF. Here too you pass -synctex=1 to the engine (platex / uplatex). The engine first writes the .synctex.gz in DVI coordinates. But DVI coordinates and final-PDF coordinates differ by the offsets and magnification dvipdfmx applies, so that gap has to be reconciled after conversion.

That finishing touch is the synctex subcommand **synctex update**, whose job is “to update the SyncTeX file once a dvi/xdv → pdf filter is applied.” dvipdfmx itself has no -synctex option; instead you hand synctex update the magnification and horizontal/vertical offsets used for the conversion (-m / -x / -y, the same values passed to the filter) so the coordinates line up. In practice a higher-level tool such as ptex2pdf or latexmk runs this whole chain for you.

How each editor triggers it

SyncTeX itself is the common foundation; only the key or click that triggers forward and inverse search differs between editors and viewers. Here are some representative combinations (see each page for full setup). Note that viewers without SyncTeX support, such as Adobe Acrobat / Reader, cannot do inverse search; common choices that do are Skim (macOS), SumatraPDF (Windows), and Okular (Linux).

A final word on precision. SyncTeX maps at the granularity of typeset “boxes,” so in ordinary body text the jump is accurate enough — but inside TikZ pictures, the expansion of intricate macros, or the innards of tables, the match can round to a nearby box and land a word or two off your target. This is a limitation of the approach, not a bug.