compile-tex

name	compile-tex
description	Compile LaTeX, plain TeX, and ConTeXt documents to PDF using the texlive/texlive Docker image. Agent-agnostic notes on the bits a fresh agent gets wrong without the doc: working directory, scheme and -doc/-src semantics, the latest tag's weekly rebuild, the non-root texlive user, the latexmk and arara wrappers, and LuaLaTeX as the modern default engine.
license	MIT

Compile TeX documents with the texlive/texlive Docker image

Build LaTeX, plain TeX, and ConTeXt documents to PDF using the Island of TeX texlive/texlive image — no host TeX Live install. This file collects the bits a general-purpose agent (or human) tends to get wrong without documentation; ordinary pdflatex foo.tex–level usage is taken for granted.

Image-specific facts

• Working directory: /workdir. Mount the project source there (-v "${PWD}:/workdir"); do not invent /data, /tex, or similar.
• Default user: root. The unprivileged texlive user has shipped since 2025-02 — use --user texlive (or -u "$(id -u):$(id -g)") on Linux hosts to avoid root-owned output files. Unnecessary on macOS/Windows.
• latest tag is rebuilt weekly. Pass --pull=always to docker run so the local cache does not go stale. Omit for historic and dated tags (those change rarely).
• Schemes: minimal, basic, small, medium, full (default for latest), and context. Tag form: latest-<scheme>, e.g. latest-medium. Smaller schemes pull faster but ship fewer CTAN packages and may omit latexmk, arara, or context.
• Historic tags: TLYYYY-historic, e.g. TL2024-historic. Rebuilt monthly for OS updates only; TeX Live contents are frozen.
• -doc and -src flavors add documentation and source files for already-installed packages. They do not add more packages. If a package is missing, switch to a larger scheme or run tlmgr install <pkg> (plus tlmgr path add for new binaries on non-full schemes).

Engine choice

Default to LuaLaTeX (lualatex) for new documents: native UTF-8, OpenType / system fonts via fontspec, embedded Lua, active upstream development. For plain TeX, the equivalent default is luatex.

Pick a different engine only with a concrete reason:

• pdflatex / pdftex — legacy documents tied to the classic 8-bit toolchain, or packages that only work there.
• latex / tex — DVI output specifically (e.g. dvips workflows).

ConTeXt sources (\starttext, .mkiv/.mkxl) → context.

Magic comments are honored by editors and respected by latexmk with the matching configuration: % !TEX program=lualatex, % !TEX root=main.tex.

Build tools

The full scheme (default for latest) ships every tool below. Smaller schemes drop the heavier ones — pick a tag at least at the listed minimum scheme, or run tlmgr install <pkg> inside the container.

Tool	Use when	Min scheme
lualatex foo.tex (or pdflatex, latex)	LaTeX, single-pass, no bibliography/index.	basic
luatex foo.tex (or pdftex, tex)	Plain TeX, single-pass.	basic
latexmk -lualatex foo.tex (or -pdf)	Multi-pass; auto-runs Biber/BibTeX/makeindex; honors latexmkrc.	small
context foo.tex	ConTeXt sources.	medium (or latest-context)
arara foo.tex	Source declares its build steps as % arara: … directives.	medium

arara is part of the Island of TeX. The source declares the pipeline as magic comments:

% arara: lualatex
% arara: biber
% arara: lualatex
% arara: lualatex

When such directives (or an .araraconfig.yaml) exist, prefer arara — the source documents its own build.

Run

Mount the project at /workdir; use --pull=always for latest:

docker run --rm --pull=always -v "${PWD}:/workdir" texlive/texlive:latest \
  latexmk -lualatex -interaction=nonstopmode -halt-on-error foo.tex

PowerShell:

docker run --rm --pull=always -v "${PWD}:/workdir" texlive/texlive:latest `
  latexmk -lualatex -interaction=nonstopmode -halt-on-error foo.tex

Swap latexmk -lualatex foo.tex for any row in the Build tools table (lualatex foo.tex, arara foo.tex, context foo.tex, …).

File ownership on Linux

Run as the caller's UID/GID:

docker run --rm --pull=always -u "$(id -u):$(id -g)" -v "${PWD}:/workdir" \
  texlive/texlive:latest latexmk -lualatex foo.tex

…or use the unprivileged texlive user shipped in the image:

docker run --rm --pull=always --user texlive -v "${PWD}:/workdir" \
  texlive/texlive:latest latexmk -lualatex foo.tex

Unnecessary on macOS and Windows Docker Desktop.

Error reporting

Extract the actual error from foo.log: search for lines starting with ! together with the l.<n> line reference. Show that; do not paste the full log.

Housekeeping

• latexmk -c foo.tex — remove auxiliary files, keep the PDF.
• latexmk -C foo.tex — remove the PDF too.
• context --purge foo.tex — ConTeXt equivalent.