\engine{latexmk}
latexmk Guide
latexmk automates the multi-pass LaTeX compilation pipeline. It figures out exactly how many passes are needed, runs bibtex or biber when required, and watches source files for changes. Stop counting pdflatex runs manually.
\section{What is latexmk}
What is latexmk?
latexmk is a Perl script written by John Collins that acts as an intelligent build system for LaTeX documents. When you run latexmk -pdf, it examines the .aux, .toc, .bbl, and other auxiliary files after each pass to determine whether another pass is required. It continues running until the output stabilises — typically two to four passes for a document with bibliography and cross-references.
Automatic multi-pass
Detects when another pdflatex pass is needed by comparing auxiliary file checksums.
Dependency tracking
Watches .tex, .bib, images, and included files. Recompiles only when something actually changes.
Configurable via .latexmkrc
Per-project and global configuration files control engine choice, output directories, and custom rules.
\subsection{Basic Usage}
Basic latexmk commands
latexmk is included in every TeX Live installation. These are the commands you will use most often — from a simple PDF compile to file watching.
# Compile with pdfLaTeX (default) — runs as many passes as needed
latexmk -pdf document.tex
# Compile with XeLaTeX
latexmk -xelatex document.tex
# Compile with LuaLaTeX
latexmk -lualatex document.tex
# Compile and open the resulting PDF
latexmk -pdf -pv document.tex
# Watch for file changes and recompile automatically
latexmk -pdf -pvc document.tex
# Clean up auxiliary files (.aux, .log, .toc, .out …)
latexmk -c document.tex
# Clean up ALL generated files including the PDF
latexmk -C document.tex-pdfCompile to PDF using pdfLaTeX (default engine)-xelatexCompile to PDF using XeLaTeX-lualatexCompile to PDF using LuaLaTeX-pvcPreview continuously — watch files and recompile on change-cClean auxiliary files but keep the PDF-CClean all generated files including the PDF\subsection{.latexmkrc}
Configuring latexmk with .latexmkrc
A .latexmkrc file in your project root tells latexmk which engine to use, where to write output files, and how to handle bibliography. This eliminates the need for long command-line flags.
# .latexmkrc — project-level configuration
# Place this file in the same directory as your .tex file
# Use pdfLaTeX by default
$pdf_mode = 1;
# Or use XeLaTeX
# $pdf_mode = 5;
# Or use LuaLaTeX
# $pdf_mode = 4;
# Custom PDF viewer (optional)
$pdf_previewer = 'evince %S';
# Run biber instead of bibtex for bibliography
$biber = 'biber %O %S';
# Write output files to ./build directory
$out_dir = 'build';
# Extra extensions to clean with latexmk -c
@generated_exts = (@generated_exts, 'synctex.gz', 'run.xml', 'bcf');
# Extra dependencies to watch (e.g. bibliography files)
@default_files = ('document.tex');$pdf_mode values
$pdf_mode = 1— pdfLaTeX $pdf_mode = 4— LuaLaTeX $pdf_mode = 5 — XeLaTeX
\section{CI/CD Integration}
latexmk in GitHub Actions
The most common CI/CD pattern for LaTeX is to compile on push to main and upload the PDF as an artifact. The workflow below uses the teatimeguest/setup-texlive-action action to install TeX Live — which includes latexmk — on the runner.
# .github/workflows/latex.yml
name: Compile LaTeX
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install TeX Live
uses: teatimeguest/setup-texlive-action@v3
with:
packages: scheme-small latexmk
- name: Compile with latexmk
run: |
latexmk -pdf -interaction=nonstopmode -halt-on-error document.tex
- name: Upload PDF artifact
uses: actions/upload-artifact@v4
with:
name: document-pdf
path: document.pdflatexmk runs as many pdflatex passes as needed — no need to count passes in your workflow
Use -halt-on-error with -interaction=nonstopmode to fail the CI job on any LaTeX error
Upload the PDF as an artifact to make it downloadable from the Actions run summary
For faster CI runs, replace the local TeX Live installation with the FormaTeX API — one HTTP request, no TeX Live setup
\section{Comparison}
latexmk vs manual pdflatex
For a simple one-page document, manual pdflatex is equivalent. For anything with cross-references, a bibliography, or a table of contents, latexmk is strictly better.
\subsection{FormaTeX Alternative}
Skip the local TeX installation entirely
latexmk solves the multi-pass problem on your local machine. FormaTeX solves the infrastructure problem: no TeX Live, no latexmk, no Docker images — just an HTTP request that returns a PDF.
With local latexmk
- Install TeX Live (~5GB)
- Configure .latexmkrc per project
- Manage TeX Live updates
- Set up CI runner with TeX Live action
- Debug engine-specific failures locally
With FormaTeX API
- No installation — API call returns PDF
- Choose engine via engine field
- Always-current TeX Live on the server
- CI integrates in one curl command
- Same engine, same output, every time
Automate LaTeX compilation at scale
FormaTeX handles multi-pass compilation server-side. Pass "engine": "latexmk" to run the full latexmk pipeline — bibliography, cross-references, everything resolved in one API call.