Skip to content

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

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 the jax install step) 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). The same change as QuantEcon/lecture-python-programming#664; collab.yml runs 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's cache.yml builds 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, and publish.yml reuses cache.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

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
Copilot AI balanced review requested due to automatic review settings November 18, 2026 23:24

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.

🟡 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.

Comment thread .github/workflows/cache.yml Outdated
# 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"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

Comment thread .github/workflows/ci.yml Outdated
# 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"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

Comment thread .github/workflows/publish.yml Outdated
# 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"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

📖 Netlify Preview Ready!

Preview URL: https://pr-1134--sunny-cactus-210e3e.netlify.app

Commit: a1b09de


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
mmcky added a commit to QuantEcon/lecture-jax that referenced this pull request Nov 18, 2026
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
mmcky added a commit to QuantEcon/lecture-python-programming that referenced this pull request Nov 18, 2026
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
@mmcky
mmcky merged commit eb2ba52 into main Nov 19, 2026
2 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