Use CoreText to find macOS fonts by iccir · Pull Request #31977 · matplotlib/matplotlib · GitHub

Closes #28249
Closes #31965

Why is this change necessary?

Prior to this change, findSystemFonts() in font_manager.py called system_profiler -xml SPFontsDataType. This subprocess would load 1000+ font files in order to parse localized names. As we only need font paths, we can instead query CoreText directly. This finishes in ~63ms on my machine instead of ~7 seconds.

Differences in found fonts

system_profiler uses the private kCTFontCollectionIncludeInvisibleFontsOption option to find "invisible" fonts. These are fonts with names starting with '.'. These fonts are typically unavailable using the standard macOS font APIs. On my machine (macOS 14.8), the following fonts are "invisible":

  /System/Library/Fonts/ADTNumeric.ttc
  /System/Library/Fonts/AquaKana.ttc
  /System/Library/Fonts/HelveLTMM
  /System/Library/Fonts/Keyboard.ttf
  /System/Library/Fonts/LastResort.otf
  /System/Library/Fonts/NewYork.ttf
  /System/Library/Fonts/NewYorkItalic.ttf
  /System/Library/Fonts/SFArabic.ttf
  /System/Library/Fonts/SFArabicRounded.ttf
  /System/Library/Fonts/SFArmenian.ttf
  /System/Library/Fonts/SFArmenianRounded.ttf
  /System/Library/Fonts/SFCamera.ttf
  /System/Library/Fonts/SFCompact.ttf
  /System/Library/Fonts/SFCompactItalic.ttf
  /System/Library/Fonts/SFCompactRounded.ttf
  /System/Library/Fonts/SFGeorgian.ttf
  /System/Library/Fonts/SFGeorgianRounded.ttf
  /System/Library/Fonts/SFHebrew.ttf
  /System/Library/Fonts/SFHebrewRounded.ttf
  /System/Library/Fonts/SFNS.ttf
  /System/Library/Fonts/SFNSItalic.ttf
  /System/Library/Fonts/SFNSMono.ttf
  /System/Library/Fonts/SFNSMonoItalic.ttf
  /System/Library/Fonts/SFNSRounded.ttf
  /System/Library/Fonts/ThonburiUI.ttc
  /System/Library/Fonts/TimesLTMM

My change uses the CTFontCollectionCreateFromAvailableFonts() without this private option; hence, these fonts will be missing from the list returned by _get_macos_fonts().

However, font_manager.py later re-scans the "/System/Library/Fonts" path, so it should discover these invisible fonts at that time.

I tested this change on macOS Mojave (10.14) and macOS Sonoma (14.8). I was unable to test on 10.12 or 10.13 as I updated my 10.12 test device to 10.14. The CoreText API used has been available since 10.5, so I do not foresee any compatibility issues.

AI Disclosure

The original C-based implementation in #31965 is my own without any usage of AI. I used AI to help me convert it to C++ and return a py::set (my original implementation printed the paths). I used AI to check the resulting files and verify that I was following the correct formatting guidelines.

PR checklist

"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

Suggested change

      
            def find_available_fonts() ->  set[str] | None: ...
          
            def get_available_fonts() ->  set[str] | None: ...

should this be a py::set() call so that you can iterate it on the returning item even on a non macos platform? It is private, so probably not a big deal either way, but you are calling it as for x in None in the _get_macos helper above which would raise instead of returning empty.

I was trying to mimic the "on other platforms, returns None" in Win32_GetCurrentProcessExplicitAppUserModelID and Win32_GetForegroundWindow.

I think _get_macos_fonts() should be changed to check for None rather than returning an empty set. To me, an empty set would indicate that the platform-specific code ran but found no fonts.

I think raising NotImplementedError might be the proper solution if the other functions in that file would do the same? I'm not sure (still learning!) :)

Co-authored-by: Greg Lucas <greg.m.lucas@gmail.com>

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

I happened across foliojs/font-manager#19 while looking at these functions. Is that also a problem in this implementation (and was it something that we supported before)?

I happened across foliojs/font-manager#19 while looking at these functions. Is that also a problem in this implementation (and was it something that we supported before)?

I'm not sure what is going on in the linked bug. ~/Library/Fonts is being checked on my test devices:

>>> pprint.pp([x for x in _c_internal_utils.get_available_fonts() if "iccir" in x])
['/Users/iccir/Library/Fonts/SF-Mono-Light.otf',
 '/Users/iccir/Library/Fonts/SF-Mono-Bold.otf',
 '/Users/iccir/Library/Fonts/DINishCondensed-Heavy.ttf',
 '/Users/iccir/Library/Fonts/DINish-Italic.otf',
…

My suspicion is one of the following:

There was a bug circa-2017 with CoreText.
The node process didn't have access to ~/Library/Fonts. I wouldn't expect this back in 2017. It would be more common nowadays with all of the additional macOS restrictions.
The user was placing fonts in ~/Library/Fonts without actually registering them with macOS via Font Book. Although the user mentions that they are available in TextEdit so I wouldn't expect this to be the case.

I'm leaning towards 1.

In any case, our previous implemented ran system_profiler as a subprocess, which also uses CTFontCollectionCreateFromAvailableFonts() internally. It's possible that ~/Library/Fonts isn't being accessed on some versions of macOS, but I wouldn't expect that to be a regression from the previous implementation.

I did some more digging last night.

system_profiler calls CTFontCollectionCreateFromAvailableFonts() with kCTFontCollectionIncludeDisabledFontsOption turned on. This means that fonts explicitly deactivated/disabled by the user were being included in _get_macos_fonts().

The new code calls CTFontCollectionCreateFromAvailableFonts() with NULL, so deactivated/disabled fonts will not be included.

This is a subtle change of behavior, but I'm not sure if the old behavior is correct. There are situations where a user may have multiple user-level fonts installed with the same name and wants to deactivate one of them.

Assuming we want to change this behavior, should the version number of the font cache be bumped in font_manager.py? It's currently:

    __version__ = '3.11.0'

Hmm, yes, I think that is correct, as we did the same thing for Windows: #22859

You can bump the cache key to 3.12.0a1 or similar.

iccir added 2 commits July 1, 2026 11:00

Use CoreText to find macOS fonts

50cbd1e

Fix mypy-stubtest failure

aa947c8

melissawm added GUI: MacOSX topic: text/fonts labels Jul 9, 2026

QuLogic mentioned this pull request Jul 16, 2026

[MNT]: findSystemFonts - Use system API instead to look into folder #24001

Closed

QuLogic linked an issue Jul 16, 2026 that may be closed by this pull request

[MNT]: findSystemFonts - Use system API instead to look into folder #24001

Closed

greglucas reviewed Jul 24, 2026

View reviewed changes

Changes based on feedback

0122e2d

github-actions Bot removed GUI: MacOSX topic: text/fonts labels Jul 24, 2026

greglucas approved these changes Jul 24, 2026

View reviewed changes

Comment thread lib/matplotlib/tests/test_font_manager.py Outdated

Update lib/matplotlib/tests/test_font_manager.py

dbbcd59

Co-authored-by: Greg Lucas <greg.m.lucas@gmail.com>

QuLogic reviewed Jul 28, 2026

View reviewed changes

iccir and others added 6 commits July 27, 2026 19:42

Update lib/matplotlib/tests/test_font_manager.py

058dfc0

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Update lib/matplotlib/tests/test_font_manager.py

a592719

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Update lib/matplotlib/tests/test_font_manager.py

a980e73

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Update src/_c_internal_utils.cpp

aca9614

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Use snake_case

22e92ce

Use std::make_unique instead of new

f76a6ed

melissawm added the OS: Apple label Jul 28, 2026

QuLogic approved these changes Jul 29, 2026

View reviewed changes

Bump font manager version due to macOS CoreText change

7a279ce

QuLogic merged commit 8aedfd2 into matplotlib:main Aug 6, 2026
42 checks passed

QuLogic added this to the v3.12.0 milestone Aug 6, 2026

iccir deleted the coretext-find-fonts branch September 7, 2026 16:57

iccir mentioned this pull request Sep 9, 2026

[Bug]: macOS font discovery raises KeyError('_items') for an incomplete system_profiler font record #32328

Open

happyarts mentioned this pull request Sep 17, 2026

Keep matplotlib off the system fonts in the diarization worker, so a broken font record on macOS no longer kills speaker detection kaixxx/noScribe#346

Merged

@@ @@ -1,5 +1,6 @@ @@
               def display_is_valid() -> bool: ...
               def xdisplay_is_valid() -> bool: ...
+              def find_available_fonts() ->  set[str] | None: ...

Use CoreText to find macOS fonts by iccir · Pull Request #31977 · matplotlib/matplotlib · GitHub

Repository navigation

Use CoreText to find macOS fonts - #31977

Use CoreText to find macOS fonts#31977
QuLogic merged 11 commits into
matplotlib:mainfrom
iccir:coretext-find-fonts

iccir commented Jul 1, 2026

Uh oh!

Uh oh!

greglucas Jul 24, 2026

Uh oh!

greglucas Jul 24, 2026

Uh oh!

iccir Jul 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuLogic commented Jul 29, 2026

Uh oh!

iccir commented Jul 29, 2026 •
edited
Loading

Uh oh!

Uh oh!

iccir commented Jul 29, 2026

Uh oh!

QuLogic commented Aug 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	def find_available_fonts() -> set[str] \| None: ...
	def get_available_fonts() -> set[str] \| None: ...

+                  }
+                  return fonts;
+              #else
+                  return py::none();

Use CoreText to find macOS fonts by iccir · Pull Request #31977 · matplotlib/matplotlib · GitHub

Repository navigation

Use CoreText to find macOS fonts - #31977

Use CoreText to find macOS fonts#31977QuLogic merged 11 commits intomatplotlib:mainmatplotlib/matplotlib:mainfrom iccir:coretext-find-fontsiccir/matplotlib:coretext-find-fontsCopy head branch name to clipboard

Conversation

iccir commented Jul 1, 2026

Why is this change necessary?

Differences in found fonts

AI Disclosure

PR checklist

Uh oh!

Uh oh!

greglucas Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

greglucas Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

iccir Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuLogic commented Jul 29, 2026

Uh oh!

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

Uh oh!

Uh oh!

iccir commented Jul 29, 2026

Uh oh!

QuLogic commented Aug 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Use CoreText to find macOS fonts#31977
QuLogic merged 11 commits into
matplotlib:mainfrom
iccir:coretext-find-fonts

iccir commented Jul 29, 2026 •
edited
Loading