PERF: Let FreeType read font data from memory instead of through Python by scottshambaugh · Pull Request #32064 · matplotlib/matplotlib

scottshambaugh · 2026-07-18T18:07:02Z

PR summary

FT2Font currently re-reads data from the font file on every glyph load, costing 10 lseek and 4 read syscalls per glyph on every FT2Font.set_text call. This is still relatively fast on a local filesystem, but imposes huge IO strain on remote filesystems (WSL's /mnt/c bridge to windows in my particular case, but also network mounts).

This PR mmaps the font file and hands the buffer to FreeType, so glyph loads skip the Python layer and only touch the filesystem once. Python still handles opening the file for unicode path handling, with a test added for that.

Note that we build freetype with meson's auto_features=disabled, so its mmap=auto line was a noop and removed in this PR. It doesn't matter here since we're handing freetype the data instead of a path.

Measuring syscalls directly on the font file for 30 glyphs across 10 set_text calls, we drop from ~2900 lseeks and ~1200 reads to 1 lseek and 1 mmap. When using the local linux filesystem on my machine, set_text is ~15x faster and a savefig on an empty plot is ~1.5x faster. When I cross the WSL filesystem boundary, the speedups are ~1000x for set_text and ~10x for savefig.

import matplotlib.pyplot as plt
for _ in range(50):
    fig, ax = plt.subplots()
    fig.savefig("/dev/null", format="png")
    plt.close(fig)

Before (Across WSL filesystem boundary):

After:

AI Disclosure

Discovered myself, investigated and prototyped with claude code, manually reviewed / edited.

PR checklist

[n/a] "closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
[n/a] Plotting related features are demonstrated in an example
[n/a] New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

tacaswell · 2026-07-18T21:57:26Z

How does this intersect with a (hot) disk cache? What is the memory hit (discussed this in person with @ksunden ).

scottshambaugh · 2026-07-19T16:47:18Z

My understanding of how this works is that the disk cache is on the kernel side, and doesn't help with the userspace calls to fetch that data (much less the python overhead). I believe the reason the WSL bridge/network drives are so much slower here is because they can't have a disk cache. mmap forces that cache to happen, and skips the kernel for direct memory reads, so there's no additional memory usage (for local filesystems) or syscall/python overhead (for either). If the file changes underneath while we're running then the values we've already loaded to ram will be stale, but I don't think that's behavior we need to protect for.

Measuring it, DejaVuSans is ~738kB on disk, and for the ascii character set mmap lazily loads only ~292kB of this into ram (mostly headers). But again, I think this memory usage is just the disk cache made explicit and not actually additional. It's a free win AFAICT.

tacaswell · 2026-07-22T03:17:25Z

@QuLogic How do we get the WASM tests to run?

QuLogic · 2026-07-23T02:36:41Z

@QuLogic How do we get the WASM tests to run?

One could normally just add the cibuildwheel label, but currently the WASM build doesn't run any tests because they are broken, so you will only get a compile check.

QuLogic · 2026-07-23T05:07:29Z

+            // Fall back to a copy of the whole file into memory.
+            data = self->py_file.attr("read")();


I'm a bit wary of this. While most single-language fonts can be relatively small, fonts that cover large swaths of Unicode, like CJK fonts, may be much bigger. On Google Fonts, the largest font is Chiron Sung HK which is over 50 MB. And if someone configures fallback fonts, they will now all get loaded in their entirety, causing a large increase in memory usage after this.

As a worst case, if we start supporting full family loading (i.e., all weights of a family), then Noto Sans CJK in all its weights takes up 125MiB:

$ du -hsc /usr/share/fonts/google-noto-sans-cjk-fonts/* 19M /usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Black.ttc 20M /usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Bold.ttc 18M /usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-DemiLight.ttc 18M /usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Light.ttc 18M /usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Medium.ttc 19M /usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Regular.ttc 16M /usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Thin.ttc 125M total

Would it be an option to do the pre-read into memory only for "small" fonts? With a suitable definitions of small, possibly even configurable.
This could still yield a speed up for common cases but prevent excessive memory use.

I'd be okay with moving this fallback back to the original implementation, I think the remaining slow path of WASI reading fonts over a network is a super edge case and we're getting into a storage vs speed tradeoff regardless.

Pushed that as a new commit, can revert pending discussion.

…h python More targeted error handling

scottshambaugh added this to the v3.12.0 milestone Jul 18, 2026

scottshambaugh requested a review from QuLogic July 18, 2026 18:07

scottshambaugh added Performance topic: text/fonts OS: Microsoft/WSL labels Jul 18, 2026

scottshambaugh force-pushed the font_mmap branch from bdf46d9 to 3b5fe33 Compare July 21, 2026 21:01

tacaswell reviewed Jul 22, 2026

View reviewed changes

Comment thread src/ft2font_wrapper.cpp

QuLogic reviewed Jul 23, 2026

View reviewed changes

scottshambaugh force-pushed the font_mmap branch from 9f6d4c0 to d29a0b9 Compare July 23, 2026 16:58

scottshambaugh mentioned this pull request Jul 25, 2026

PERF: Text rendering speedups #32120

Open

2 tasks

QuLogic approved these changes Jul 29, 2026

View reviewed changes

Comment thread extern/meson.build

scottshambaugh added 5 commits July 29, 2026 08:26

Use mmap when reading font files, to stop per-glyph file reads throug…

c0fd104

…h python More targeted error handling

Handle a mmap import error for reading fonts

047ee9b

Restore loading glyphs through python as the font fallback to mmap

b7e9b02

Consolidate code block

4b22288

explicitly disable freetype mmap

a029d55

scottshambaugh force-pushed the font_mmap branch from 960f6a2 to a029d55 Compare July 29, 2026 14:26

tacaswell approved these changes Aug 7, 2026

View reviewed changes

tacaswell merged commit 0098e7f into matplotlib:main Aug 7, 2026
42 checks passed

Navigation Menu

Uh oh!

Uh oh!

PERF: Let FreeType read font data from memory instead of through Python - #32064

PERF: Let FreeType read font data from memory instead of through Python#32064
tacaswell merged 5 commits into
matplotlib:mainfrom
scottshambaugh:font_mmap

scottshambaugh commented Jul 18, 2026 •

edited

Loading

Uh oh!

tacaswell commented Jul 18, 2026

Uh oh!

scottshambaugh commented Jul 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

tacaswell commented Jul 22, 2026

Uh oh!

QuLogic commented Jul 23, 2026

Uh oh!

Uh oh!

Uh oh!

QuLogic Jul 23, 2026

Uh oh!

timhoffm Jul 23, 2026 •

edited

Loading

Uh oh!

scottshambaugh Jul 23, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		// Fall back to a copy of the whole file into memory.
		data = self->py_file.attr("read")();

Uh oh!

Uh oh!

Conversation

scottshambaugh commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR summary

AI Disclosure

PR checklist

Uh oh!

tacaswell commented Jul 18, 2026

Uh oh!

scottshambaugh commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

tacaswell commented Jul 22, 2026

Uh oh!

QuLogic commented Jul 23, 2026

Uh oh!

Uh oh!

Uh oh!

QuLogic Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

timhoffm Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scottshambaugh Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

scottshambaugh commented Jul 18, 2026 •

edited

Loading

scottshambaugh commented Jul 19, 2026 •

edited

Loading

timhoffm Jul 23, 2026 •

edited

Loading

scottshambaugh Jul 23, 2026 •

edited

Loading