agent's nbconvert to pdf ran xelatex in a container without fonts: missing glyphs

TL;DR

The PDF builds 'successfully' but text shows as blank boxes or missing glyphs: xelatex is present, but the container image never installed the fonts the document requests. Install the missing font packages in the image (the TeX Live font collections or the system fonts the template uses) and rebuild. If you cannot change the image, switch the document to fonts that are already present and re-export.

agent's nbconvert to pdf ran xelatex in a container without fonts: missing glyphs

Use this when

• The PDF generates but characters render as empty boxes or tofu blocks.
• The same notebook exports a perfect PDF on a laptop but a broken one in the container.
• The xelatex log warns about missing fonts while the build exits zero.

Not for this skill when

• nbconvert fails with 'xelatex not found'. That is a missing TeX installation, a different fix.
• The build fails with LaTeX errors on the content. That is a markup problem, not a font problem.

Steps

1. Confirm the symptom is fonts: open the PDF and look for tofu boxes, then grep the xelatex log for font warnings. Expected: warnings naming the missing font files.
2. Identify which fonts the document needs: check the nbconvert template and any custom LaTeX preamble for fontspec font names. Expected: a concrete list of required fonts.
3. Check what the container has: list installed TeX font packages and system fonts in the image. Expected: the required fonts are absent, explaining the laptop-vs-container split.
4. Install the fonts in the image: add the TeX Live font collections (or the OS font packages) to the Dockerfile and rebuild. Expected: the image build log shows the font packages installing.
5. Re-run the export in the new image: jupyter nbconvert --to pdf notebook.ipynb. Expected: the PDF renders all glyphs correctly.
6. If the image cannot change, switch the document's fonts to ones present (a widely available serif/sans pair) and re-export. Expected: correct rendering with the substituted fonts.

Tool compatibility

nbconvert 7.x PDF exporter; xelatex from TeX Live 2022+; Docker/OCI images; Linux containers.

Variant phrasings

nbconvert pdf missing glyphs container

The container phrasing. Install the font packages in the image and rebuild.

xelatex pdf blank boxes characters docker

The symptom phrasing. The tofu boxes are missing fonts, not missing xelatex.

jupyter pdf export fonts not found

The general phrasing. Match the document's font list against the image's installed fonts.

Why it happens

PDF export has two halves that fail independently: xelatex the engine, and the fonts the document asks for. Minimal container images install the engine (because the Dockerfile says 'texlive') but skip the multi-hundred-megabyte font collections to keep the image small, and xelatex degrades gracefully, substituting nothing and leaving blank glyphs instead of failing. The laptop works because desktop TeX installations bundle the full font set. The fix is therefore an image-content problem, not a LaTeX problem: the build environment must contain the same fonts the document references, pinned like any other dependency.

Edge cases / pitfalls

• Font package names differ across TeX Live years and OS package managers. Verify the exact package that provides the font file, not just a similarly named one.
• Custom corporate fonts need licensing and manual installation into the image; they will never come from a package manager.
• Caching the PDF across image rebuilds can serve the old broken PDF. Invalidate the export cache when the image changes.
• Agents that generate the Dockerfile should treat fonts as dependencies of the export step and fail the build loudly if a required font is absent.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstHlYDjY3qJd9xbDy1V9OEQ