Skip to content

Raise ImportError when cairocffi cannot load cairo - #32400

Merged
ayshih merged 2 commits into
matplotlib:mainfrom
iccir:catch-oserror
Sep 28, 2026
Merged

ayshih merged 2 commits into
matplotlib:mainfrom
iccir:catch-oserror

Conversation

@iccir

@iccir iccir commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

PR summary

On macOS, trying to run pytest with cairocffi installed but no cairo produces an OSError from dlopen():

… ERROR collecting lib/matplotlib/tests/test_backends_rendering.py …
lib/matplotlib/backends/backend_cairo.py:18: in <module>
    import cairo
E   ModuleNotFoundError: No module named 'cairo'

During handling of the above exception, another exception occurred:
lib/matplotlib/tests/test_backends_rendering.py:21: in <module>
    from matplotlib.backends.backend_cairo import RendererCairo, cairo
lib/matplotlib/backends/backend_cairo.py:24: in <module>
    import cairocffi as cairo
.venv/lib/python3.14/site-packages/cairocffi/__init__.py:60: in <module>
    cairo = dlopen(
.venv/lib/python3.14/site-packages/cairocffi/__init__.py:57: in dlopen
    raise OSError(error_message)  # pragma: no cover
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
E   OSError: no library called "cairo-2" was found
E   no library called "cairo" was found
E   no library called "libcairo-2" was found
E   cannot load library 'libcairo.so.2': dlopen(libcairo.so.2, 0x0002): tried:
'libcairo.so.2' (no such file),
'/System/Volumes/Preboot/Cryptexes/OSlibcairo.so.2' (no such file),
'/usr/lib/libcairo.so.2' (no such file, not in dyld cache),
'libcairo.so.2' (no such file).
Additionally, ctypes.util.find_library() did not manage to locate a library
called 'libcairo.so.2'

Originally, I added OSError to test_backends_rendering.py to fix this.

However, I decided that it would be better to catch the OSError in backend_cairo.py and then re-throw as an ImportError with a better error message.

AI Disclosure

None used.

PR quality check

  • Use an expressive title, e.g. "Fix title font property precedence"
  • [N/A] New and changed code is tested
  • [N/A] Plotting related features are demonstrated in an example
  • [N/A] New features and API changes have release notes
  • [N/A] Documentation complies with general and docstring guidelines

Comment thread lib/matplotlib/tests/test_backends_rendering.py Outdated
@iccir iccir changed the title Fix test_backends_rendering when cairo is missing Raise ImportError when cairocffi cannot load cairo Sep 26, 2026

@ayshih ayshih 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.

Looks good to me!

Comment thread lib/matplotlib/backends/backend_cairo.py Outdated
@ayshih
ayshih merged commit adaadbd into matplotlib:main Sep 28, 2026
37 of 38 checks passed
@ayshih ayshih added this to the v3.11.3 milestone Sep 29, 2026
@ayshih

ayshih commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

@meeseeksdev backport to v3.11.x

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants