Skip to content

Build matplotlib's font cache before the build - #664

Merged
mmcky merged 2 commits into
mainfrom
warm-font-cache
Nov 19, 2026
Merged

mmcky merged 2 commits into
mainfrom
warm-font-cache

Conversation

@mmcky

@mmcky mmcky commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What

One step, python -c "import matplotlib.font_manager", after the environment is complete (after "Install JAX and Numpyro") in cache.yml, ci.yml and publish.yml. It builds matplotlib's font cache before any notebook runs (the font manager builds it on import, with no plotting backend involved).

Why

A freshly launched runner has no font cache, so the first matplotlib import scans the system fonts (about a thousand files) from a cold disk. In an instrumented pair of cache.yml builds that took 13.1 s on main and 10.1 s on a branch (run 44418219319, run 44418224343), against 1.9 s when repeated warm. Past 5 s matplotlib prints "Matplotlib is building the font cache; this may take a moment." into the output of the first notebook that imports it, about_py, so whether that line reached the page depended on the instance: it did in those two builds and in two of #663's, and not in main's two before them. Since publish.yml reuses cache.yml's executed outputs, a weekly cache run could have put it on the live "About Python" page.

What it changes for a page

Nothing, except that the line can no longer appear. The step runs no lecture code and changes no package; it only builds the cache that the first notebook would otherwise build. Each workflow takes a few seconds longer before the build, and about_py's execution as much shorter.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL

On a freshly launched runner the first matplotlib import scans the system fonts from a cold disk, which took 10 to 13 s in an instrumented pair of cache.yml builds (1.9 s warm). Past 5 s matplotlib prints "Matplotlib is building the font cache; this may take a moment." into the output of the first notebook that imports it, about_py, so whether that line reaches the page depended on the instance. One step after the environment is complete, in cache.yml, ci.yml and publish.yml, builds the cache first.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The change is a straightforward, low-risk workflow update that consistently pre-builds Matplotlib’s font cache across CI, cache, and publish pipelines, with no active issues noted in the provided review evidence.

No open issues 🎉

What changed in this PR

Adds an explicit CI warm-up step to pre-build Matplotlib’s font cache before any notebooks run, avoiding cold-start font scans and preventing the “Matplotlib is building the font cache…” message from appearing in rendered outputs.

Changes:

  • Added a Matplotlib font-cache warm-up step after the environment/JAX setup in the cache, CI, and publish GitHub Actions workflows.
  • Ensured consistent pre-caching behavior across workflows so notebook execution and published outputs are not timing-dependent.
File Description
.github/​workflows/​publish.yml Adds a Matplotlib font-cache warm-up step in the publish workflow prior to consuming executed outputs to avoid first-import font cache noise and latency.
.github/​workflows/​ci.yml Adds a Matplotlib font-cache warm-up step to CI after environment setup so PR builds don’t incur the cold font scan during notebook execution.
.github/​workflows/​cache.yml Adds a Matplotlib font-cache warm-up step before running the cache build so notebook execution starts with an already-built font cache.

Review effort: Balanced
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

matplotlib.font_manager builds the cache on import with no backend involved, so the step cannot depend on which backend the runner would choose (Copilot's review on QuantEcon/lecture-python.myst#1134). pyplot would not have failed there: on a Linux runner without a display matplotlib's automatic choice is Agg.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL
@mmcky
mmcky merged commit 6ddf088 into main Nov 19, 2026
4 checks passed
@mmcky
mmcky deleted the warm-font-cache branch November 19, 2026 01:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants