Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pip cannot build pycairo (Could not build wheels for pycairo)

ErrorERROR: Could not build wheels for pycairo, which is required to install pyproject.toml-based projects

Short answer

pycairo is a C extension. Installing it from source needs pkg-config, the cairo development headers and, on Linux, the Python headers. The error is those packages missing. On Ubuntu, Debian or WSL install libcairo2-dev, pkg-config and python3-dev with apt, then run pip again. Fedora and macOS have their own names.

  • Applies to pycairo 1.2x, Python 3.12, Ubuntu 24.04, WSL 2, Fedora, macOS with Homebrew
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the two things the build looks for: pkg-config and the cairo package it should find.

    pkg-config --version
    pkg-config --modversion cairo
  2. 2Match what you see, then jump to its fix

    1. 1The build fails on Ubuntu, Debian or inside WSL, and pkg-config or the cairo package is missingDebian, Ubuntu or WSL has no cairo headers or pkg-configFix
    2. 2The same failure on Fedora or another dnf-based systemFedora is missing cairo-develFix
    3. 3The build fails on a Mac, and brew list shows no cairomacOS has no Homebrew cairo or pkg-configFix
    4. 4pip succeeded, but import cairo fails, often after a cairo upgradepycairo installs but import fails, because of a stale cached wheelFix

What does the error look like?

  • ERROR: Could not build wheels for pycairo, which is required to install pyproject.toml-based projects

Cause 1 of 4

Debian, Ubuntu or WSL has no cairo headers or pkg-config

1Check

The pycairo guide says installing it requires pkg-config and cairo including its headers. Check which of the three Debian packages are missing.

dpkg -s libcairo2-dev pkg-config python3-dev 2>&1 | grep -E 'Package|Status'

2Fix

Install the three packages from the pycairo guide, then install again.

sudo apt install libcairo2-dev pkg-config python3-dev
python3 -m pip install pycairo

3Verify

The module imports.

python3 -c "import cairo"

Confirmed by pycairo.readthedocs.io

Did this fix it?

Cause 2 of 4

Fedora is missing cairo-devel

1Check

Fedora names the packages differently. Query them with rpm.

rpm -q cairo-devel python3-devel

2Fix

Use the package names the pycairo guide lists for Fedora.

sudo dnf install cairo-devel pkg-config python3-devel
python3 -m pip install pycairo

3Verify

The module imports.

python3 -c "import cairo"

Confirmed by pycairo.readthedocs.io

Did this fix it?

Cause 3 of 4

macOS has no Homebrew cairo or pkg-config

1Check

Homebrew provides both pieces on macOS.

brew list cairo pkg-config

2Fix

Install them, then retry pip.

brew install cairo pkg-config
python3 -m pip install pycairo

3Verify

The module imports.

python3 -c "import cairo"

Confirmed by pycairo.readthedocs.io

Did this fix it?

Cause 4 of 4

pycairo installs but import fails, because of a stale cached wheel

1Check

The pycairo guide says pip's cached wheels may have been built against a different cairo version.

python3 -c "import cairo"

2Fix

Reinstall without the cache.

python3 -m pip install --force-reinstall --no-cache-dir pycairo

3Verify

import cairo now works.

python3 -c "import cairo"

Confirmed by pycairo.readthedocs.io

Did this fix it?

How do I stop it coming back?

  • Install the system packages before pip install for any library that wraps a C library (manim, pygobject and similar).
  • Put the apt line in your setup script or Dockerfile, so a fresh machine does not repeat the failure.
  • Install into a virtual environment so a failed build cannot touch system Python.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.