Does LaTeX have any built-in way to detect stale .aux files without a full clean rebuild?

Question

LaTeX stores cross-references, table of contents entries, and bibliography data in auxiliary files (.aux, .toc, .bbl) between compilation passes. These files behave like a persistent cache: after structural edits such as removing a section or deleting a label, a single compile can produce incorrect page numbers or dangling references until enough passes regenerate them.

Build tools like latexmk rerun LaTeX until the auxiliary files stabilize, but this heuristic does not reliably catch every kind of semantic staleness, and the documented workaround of deleting all auxiliary files forces an expensive full rebuild on large documents with TikZ externalization or big bibliographies.

Assume a current LaTeX kernel (2023 or later) with latexmk as the build tool.

Does the LaTeX kernel or any core package provide a mechanism to validate or version auxiliary data so tools can detect staleness selectively, rather than recompiling everything? Is there a documented way to invalidate only the affected .aux content (for example, per-label or per-chapter via \include) instead of wiping all auxiliary files? And is there any standardized checksum or hash mechanism in the .aux format that build tools are expected to rely on?

Tasadduq Burney · Answer

Answer to the Question
LaTeX does not ship any mechanism that can tell whether an existing .aux file is “stale” and needs to be regenerated without a full clean rebuild. The kernel and core packages simply overwrite the .aux file at the end of each run; they do not embed version tags, checksums, or per‑label invalidation flags.
Why the Kernel Behaves This Way

The .aux file is a plain‑text dump of macro state (page numbers, counters, label definitions) that is rewritten in full every compilation.
There is no per‑entry metadata to signal semantic changes; the file format has never been designed for incremental validation.
Tools that need to keep a document up‑to‑date, such as latexmk, use a heuristic: they run LaTeX repeatedly until the .aux output stops changing. This works for many structural edits but cannot detect all kinds of staleness (e.g., a removed label that still appears in a reference).
Standard inclusion mechanisms (\include or \input) create separate auxiliary scopes (e.g., chapter1.aux) but they also lack any checksum or versioning. They merely isolate the file names; they do not provide selective invalidation.

What You Can Do in Practice

Use a build tool that stabilises automatically. latexmk (or similar) will keep running LaTeX until the .aux file no longer changes. This is the de‑facto standard approach for incremental builds.
Manually delete the relevant .aux files. If you know which part of the document changed (e.g., a single chapter), you can delete only that .aux file and let LaTeX regenerate it on the next run. This avoids a full clean but still forces a rebuild of the affected part.
Keep a separate “clean” script. For large projects, consider a script that deletes all .aux, .toc, .bbl, etc., only when you need a guaranteed clean state.
Track changes manually. Some teams maintain a simple list of files that have been edited and delete only the corresponding auxiliary files. This requires discipline but works around the lack of built‑in staleness detection.

When to Ask for More Information
If you are using a non‑standard build system (e.g., arara, a custom Makefile, or a continuous‑integration pipeline) and need guidance on how to integrate the above strategies, let us know the exact toolchain. That information can change the specific commands you should run.

Does LaTeX have any built-in way to detect stale .aux files without a full clean rebuild?

1 answer

Answer to the Question

Why the Kernel Behaves This Way

What You Can Do in Practice

When to Ask for More Information

Your perspective belongs here.

0 question comments