Repository navigation
Build matplotlib's font cache before the build - #1134
Conversation
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 builds on this machine image (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, so whether that line reaches a page depends on the instance. One step after the environment is complete, in cache.yml, ci.yml and publish.yml, builds the cache first. The same change as QuantEcon/lecture-python-programming#664. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL
There was a problem hiding this comment.
🟡 Changes recommended
CI reliability is still at risk because multiple GitHub Actions workflows run a headless Python import of matplotlib.pyplot without forcing a non-interactive backend, which can fail on runners that default to GUI backends.
3 open issues
What changed in this PR
This pull request updates GitHub Actions workflows to pre-build Matplotlib’s font cache right after the environment setup so notebook execution avoids the cold-start font scan and prevents timing-dependent “Matplotlib is building the font cache…” output from appearing in rendered pages.
Changes:
- Add a dedicated Matplotlib font-cache warmup step to
.github/workflows/cache.yml. - Add the same warmup step to
.github/workflows/ci.yml. - Add the same warmup step to
.github/workflows/publish.yml.
| File | Description |
|---|---|
| .github/workflows/publish.yml | Adds a step to import Matplotlib early in the publish workflow to pre-build the font cache before any notebook outputs are reused or generated. |
| .github/workflows/ci.yml | Adds a step to import Matplotlib after environment setup so CI notebook execution avoids first-import font-cache overhead and output variability. |
| .github/workflows/cache.yml | Adds a step to import Matplotlib after environment setup to build the font cache before subsequent build and caching steps run. |
Review effort: Balanced
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
| # matplotlib then prints "Matplotlib is building the font cache; this | ||
| # may take a moment." into the output of the first notebook that | ||
| # imports it. Build the cache here, so no page depends on that timing. | ||
| python -c "import matplotlib.pyplot" |
There was a problem hiding this comment.
Changed in a1b09de: the step now runs python -c "import matplotlib.font_manager", which builds the font cache on import with no backend involved, so it no longer depends on which backend the runner would pick. (pyplot would not have failed here: on a Linux runner without a display matplotlib's automatic choice is Agg, and the step passed in this PR's preview on this image.) The same change is in QuantEcon/lecture-python-programming#664 and QuantEcon/lecture-jax#373.
| # matplotlib then prints "Matplotlib is building the font cache; this | ||
| # may take a moment." into the output of the first notebook that | ||
| # imports it. Build the cache here, so no page depends on that timing. | ||
| python -c "import matplotlib.pyplot" |
There was a problem hiding this comment.
Changed in a1b09de: the step now runs python -c "import matplotlib.font_manager", which builds the font cache on import with no backend involved, so it no longer depends on which backend the runner would pick. (pyplot would not have failed here: on a Linux runner without a display matplotlib's automatic choice is Agg, and the step passed in this PR's preview on this image.) The same change is in QuantEcon/lecture-python-programming#664 and QuantEcon/lecture-jax#373.
| # matplotlib then prints "Matplotlib is building the font cache; this | ||
| # may take a moment." into the output of the first notebook that | ||
| # imports it. Build the cache here, so no page depends on that timing. | ||
| python -c "import matplotlib.pyplot" |
There was a problem hiding this comment.
Changed in a1b09de: the step now runs python -c "import matplotlib.font_manager", which builds the font cache on import with no backend involved, so it no longer depends on which backend the runner would pick. (pyplot would not have failed here: on a Linux runner without a display matplotlib's automatic choice is Agg, and the step passed in this PR's preview on this image.) The same change is in QuantEcon/lecture-python-programming#664 and QuantEcon/lecture-jax#373.
📖 Netlify Preview Ready!Preview URL: https://pr-1134--sunny-cactus-210e3e.netlify.app Commit: Build Info
|
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 #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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL

What
One step,
python -c "import matplotlib.font_manager", after the environment is complete (after the jax install step) incache.yml,ci.ymlandpublish.yml. It builds matplotlib's font cache before any notebook runs (the font manager builds it on import, with no plotting backend involved). The same change as QuantEcon/lecture-python-programming#664;collab.ymlruns in Colab's own image and is left alone.Why
These workflows run on the same machine image as programming's (
quantecon_ubuntu2404), which has no font cache, so the first matplotlib import on a freshly launched runner scans the system fonts (about a thousand files) from a cold disk. In an instrumented pair of programming'scache.ymlbuilds that took 13.1 s and 10.1 s (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, so whether that line reaches a page depends on the instance, andpublish.ymlreusescache.yml's executed outputs.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 the first notebook that plots as much shorter.
🤖 Generated with Claude Code
https://claude.ai/code/session_01WT8bMacV9Lmy1VLUc6XJoL