pip cannot build pycairo (Could not build wheels for pycairo)
ERROR: Could not build wheels for pycairo, which is required to install pyproject.toml-based projectsShort 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.
Fix it fast
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 cairo2Match what you see, then jump to its fix
- 1
The 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
The same failure on Fedora or another dnf-based systemFedora is missing cairo-develFix - 3
The build fails on a Mac, and brew list shows no cairomacOS has no Homebrew cairo or pkg-configFix - 4
pip succeeded, but import cairo fails, often after a cairo upgradepycairo installs but import fails, because of a stale cached wheelFix
- 1
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 pycairo3Verify
The module imports.
python3 -c "import cairo"Confirmed by pycairo.readthedocs.io
Cause 2 of 4
Fedora is missing cairo-devel
1Check
Fedora names the packages differently. Query them with rpm.
rpm -q cairo-devel python3-devel2Fix
Use the package names the pycairo guide lists for Fedora.
sudo dnf install cairo-devel pkg-config python3-devel
python3 -m pip install pycairo3Verify
The module imports.
python3 -c "import cairo"Confirmed by pycairo.readthedocs.io
Cause 3 of 4
macOS has no Homebrew cairo or pkg-config
1Check
Homebrew provides both pieces on macOS.
brew list cairo pkg-config2Fix
Install them, then retry pip.
brew install cairo pkg-config
python3 -m pip install pycairo3Verify
The module imports.
python3 -c "import cairo"Confirmed by pycairo.readthedocs.io
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 pycairo3Verify
import cairo now works.
python3 -c "import cairo"Confirmed by pycairo.readthedocs.io
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix