Automating LaTeX Builds with latexmk: Setup, Continuous Preview, and Recovery

The problem latexmk solves

A LaTeX document with cross-references and citations needs the engine run multiple times, plus bibtex or biber in between, before every \ref and bibliography entry resolves. Running that sequence by hand is tedious and easy to get wrong. latexmk is a Perl-based build tool bundled with TeX Live and MiKTeX that inspects the log after each pass, decides which tools still need to run, and repeats until the output is stable. One command replaces the whole rerun loop.

This guide assumes a current TeX Live or MiKTeX installation. Flag details vary slightly between distributions and versions, so check your local manual (texdoc latexmk) before depending on anything version-specific.

Prerequisites

• A working TeX distribution. Confirm with latexmk --version in a terminal; note the version for later reference.
• A document that already compiles with a manual pdflatex run, or at least is close to it. latexmk automates reruns; it does not fix broken sources.
• For continuous preview, a PDF viewer that reloads when the file changes. On Windows, some viewers lock the PDF and block rebuilds — a lightweight auto-reloading viewer avoids this.

Basic build and engine selection

Run in the project directory, with ordinary user permissions (no elevated rights needed):

latexmk -pdf main.tex

This uses pdflatex by default and runs bibtex/biber and makeindex as needed. If the document requires system fonts or specific Unicode handling, switch engines instead of changing the document:

latexmk -xelatex main.tex
latexmk -lualatex main.tex

Expected result: exit code 0, a PDF next to the source, and no ?? markers where references should be. latexmk also writes a .fdb_latexmk and .fls file pair, which it uses to track dependencies between runs — that is how it knows a rerun is unnecessary when nothing changed.

Continuous preview for iterative writing

The standard writing workflow watches the source and rebuilds on every save:

latexmk -pvc -pdf -interaction=nonstopmode -synctex=1 main.tex

What the extra flags do:

• -pvc (preview continuously) monitors source files and rebuilds on change.
• -interaction=nonstopmode prevents the engine from stopping at an interactive prompt on the first error. Essential in automation and editor integration; without it a typo can leave the build hanging silently.
• -synctex=1 generates SyncTeX data so supporting editors can jump between a source line and the matching PDF position in both directions.

With an auto-reloading viewer open, each save produces a fresh PDF within seconds. Leave the process running in a dedicated terminal; stop it with Ctrl+C.

Pinning the setup with a project latexmkrc

To make builds identical for teammates and CI, put the configuration in a .latexmkrc file in the project root instead of relying on everyone typing the same flags:

# .latexmkrc
$pdf_mode = 1;              # build with pdflatex
$out_dir = 'build';         # keep artifacts out of the source tree
$interaction = 'nonstopmode';
$synctex = 1;

Now latexmk main.tex alone reproduces the full setup, and generated files land in build/. Check the file into version control; add build/ to .gitignore.

Verifying the setup works

Before trusting the workflow on a real document, run three quick checks:

1. Reference resolution. Build a minimal document containing a \label/\ref pair and one citation. A single latexmk -pdf call should produce output with no ?? and a populated bibliography.
2. Error behavior. Introduce a deliberate syntax error, rebuild with -interaction=nonstopmode, and confirm the build reports the error and exits instead of hanging on a prompt.
3. Clean recovery. Run latexmk -C and confirm all generated artifacts, including the PDF, are removed; then rebuild from scratch successfully.

Diagnosing and recovering from build failures

When a build fails, open the .log file and search for the first line beginning with !. Errors reported later in the log are usually cascading consequences of that first one, so fixing the last message rarely helps.

If the document behaves inconsistently — references that should resolve do not, or stale content survives edits — the auxiliary files are likely in a bad state. latexmk offers two levels of cleanup, both run in the project directory:

• latexmk -c removes intermediate files (aux, log, etc.) but keeps the PDF.
• latexmk -C removes everything generated, including the PDF. Use this for a guaranteed clean rebuild.

Both are destructive to build artifacts only; your sources are untouched, and the next build regenerates what it needs. If you set $out_dir, cleanup targets that directory.

Limitations

latexmk cannot resolve errors in the source itself, and -pvc depends on the viewer cooperating — a viewer that locks the PDF will cause rebuild failures on some platforms. Custom build steps (e.g., glossaries with makeglossaries) usually work automatically but occasionally need a custom dependency declared in .latexmkrc; consult the local manual for the exact syntax your version supports.