Compile Tex

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-, 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 (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 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. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: koppor
• Source: koppor/claude-tex-skills
• License: MIT

Install and usage instructions live in the source repository linked above.