pip install pycairo报错cairo.h缺失？一文解决C编译依赖问题

说实话，这个报错我在技术社区里见过太多次了，几乎每隔几天就会冒出来一次：

pip install pycairo ... src/importcairo.c:18:10: fatal error: cairo.h: No such file or directory 18 | #include <cairo.h> | ^~~~~~~~~ compilation terminated. error: command 'gcc' failed with exit code 1

看到这个错误的人，第一反应往往是“Python是不是坏了”“pip是不是出问题了”，甚至有人直接重装了一套Python。其实都不用，这个报错和Python本身没关系，问题出在系统层面——你的机器缺少 Cairo 图形库的 C 语言开发头文件。pycairo 是 Python 对 Cairo 库的绑定封装，pip 下载到的是源码包，需要在本地调用 C 编译器编译成扩展模块。编译的时候找不到 cairo.h，自然就卡死了。

这篇文章我把自己在这种问题上的排查思路和解决办法完整梳理一遍，覆盖主流 Linux 发行版和 macOS 环境，会把 pkg-config、环境变量这些容易踩坑的细节也讲清楚。如果你实在不想折腾编译链路，后面还有几条绕开编译的替代路径，可以按需选择。

1. 先把报错从哪来这件事彻底搞清楚

很多人栽在这个问题上，是因为根本没弄明白 pip install 到底干了什么。搞清楚这一点，后面不管遇到什么“No such file or directory”都能举一反三。

1.1 pip 下载的不一定是成品，可能是源码

Python 包在 PyPI 上通常有两种分发格式：一种是 wheel，也就是预编译好的二进制包，pip 下载下来解压就能用，不需要任何编译工具；另一种是 sdist（源码包），通常是 .tar.gz 格式，里面是完整的源代码，需要 pip 在本机调用编译器构建出可用的扩展模块。

问题就出在这里：pycairo 很长一段时间里在 PyPI 上只提供 sdist 包，不提供 Linux 平台的 wheel。这意味着无论你多不想编译代码，只要用 pip 安装，就绕不开本机要有 C 编译器和 Cairo 开发库这个前提。

编译 C 扩展的本质，是用本机的 C 编译器（gcc、clang 等）把 pycairo 的 C 语言源码编译成目标文件，再和 Cairo 库链接到一起。这个过程有两个关键依赖：一是头文件，也就是以 .h 结尾的声明文件，编译器必须在编译时找到它们；二是链接库，也就是编译好之后的二进制库文件，链接器需要它们来完成最终的可执行文件。这里的 cairo.h，就是 Cairo 库对外暴露的头文件，编译器在源码里看到#include <cairo.h>这一行，就会去系统的头文件搜索路径里查找这个文件，找不到就报 No such file or directory。

打个比方，comand line 说是让你“去隔壁仓库拿一把螺丝刀”，但你走到仓库一看，货架上连螺丝刀的影子都没有，自然只能空手而归。

1.2 缺的不是运行时库，而是开发包

这是最迷惑人的一点。很多机器上 cairo 其实是装了的，因为有不少桌面程序、图形软件都依赖它，系统里明明存在 libcairo.so 这个动态库文件，为什么编译还是失败？

原因在于，Linux 系统包里分得非常细：运行时库和开发包是两回事。

Debian/Ubuntu 体系里，libcairo2 是运行时库，提供的是编译好的二进制动态库，比如 /usr/lib/x86_64-linux-gnu/libcairo.so.2，它能让已编译好的程序正常调用 Cairo 功能。但 libcairo2-dev 才是开发包，里面才包含 cairo.h 头文件、未加版本号的 libcairo.so 符号链接，以及 pkg-config 配置文件 cairo.pc。程序员编译新代码，需要的是后者。

这个道理放在很多常见的 C 库上都一样：libssl 和 libssl-dev、libjpeg 和 libjpeg-dev，都是同样的逻辑。运行时只是用来跑，开发包才是用来编译的。

所以看到 fatal error: cairo.h，你首先要明白一件事：系统里缺的不是 Cairo 本尊，而是 Cairo 的“开发版配件包”。

2. 对症下药：主流系统怎么把依赖装齐

搞清楚症状之后，治病的逻辑就很清晰了：去系统里把 Cairo 开发包装上。但每个系统的包名和命令都不一样，这部分我按实际操作场景分平台写。

2.1 Debian/Ubuntu 系：一行命令解决

如果你用的是 Debian、Ubuntu 或者基于它们的发行版（比如 Linux Mint、Pop!_OS 这些），安装命令是这样的：

sudo apt update sudo apt install libcairo2-dev pkg-config python3-dev

三个包分别解决不同的问题：

• libcairo2-dev：提供 cairo.h 头文件和链接所需的 libcairo.so，这是编译 pycairo 的核心依赖。
• pkg-config：提供 pkg-config 命令，后面会详细说，pycairo 的构建脚本依赖它来定位 Cairo 库的位置。
• python3-dev：提供 Python.h 头文件。pycairo 是 Python 的 C 扩展，编译器同样需要 Python 提供的头文件，这个包缺失会导致另一个类似的错误：fatal error: Python.h: No such file or directory。

这里提醒一句，python3-dev 的包名可能会因为 Python 版本不同而变化。如果你用的是系统自带的 Python 3，通常直接装 python3-dev 就行；如果用的是某个特定版本，比如 Python 3.11，那可能需要 python3.11-dev。具体装哪个，可以用python3 --version先确认版本号。

装完之后，建议先验证一下：

pkg-config --modversion cairo

如果输出了一个版本号，比如 1.16.0，说明 pkg-config 已经能识别到 Cairo 开发包了，再回去跑 pip install pycairo，基本就顺了。

2.2 RHEL/CentOS/Fedora 系：换一套包名

红帽系的发行版包名不一样，安装命令也不同。CentOS 7 这类老的系统用 yum：

sudo yum install cairo-devel pkgconfig python3-devel

Fedora、RHEL 9+、CentOS Stream 这些较新的系统用 dnf：

sudo dnf install cairo-devel pkgconf-pkg-config python3-devel

注意几个差别：

• cairo-devel 对应 Debian 系的 libcairo2-dev，这是红帽系开发包的命名习惯，后缀统一是 -devel。
• pkgconfig 在 Fedora 里改名叫 pkgconf-pkg-config 了，因为 Fedora 默认用 pkgconf 这个实现来替代原版 pkg-config。不过命令敲起来还是 pkg-config。
• python3-devel 同样是为了提供 Python 头文件。

红帽系还有一个细节：老版本 CentOS 7 的 Python 3 如果是通过 Software Collections 装的，比如 rh-python38，那么包名和路径都不太一样，要对应装 scl 里的 python3-devel 和 cairo-devel。这种情况相对少见，但在老的服务器上确实会碰到。

验证方式和前面一样，装完跑pkg-config --modversion cairo，能输出版本号就是成功了。

2.3 macOS 的坑：Homebrew 装了为什么还报错

macOS 上的情况稍微特殊一点。如果你用 Homebrew 装了 cairo，但 pip install pycairo 依然报 cairo.h 找不到，那十有八九是 pkg-config 查找路径的问题。

Homebrew 的默认安装位置取决于芯片类型：

• Apple Silicon（M1/M2/M3 系列）下，Homebrew 默认装在 /opt/homebrew，对应的 pkg-config 文件路径是 /opt/homebrew/lib/pkgconfig。
• Intel 芯片的老 Mac 上，Homebrew 通常装在 /usr/local，路径是 /usr/local/lib/pkgconfig。

问题是，macOS 自带的 pkg-config（如果你装了的话）默认不扫描这两个目录。它按标准的 /usr/lib/pkgconfig 和 /usr/local/lib/pkgconfig 去找，但 Apple Silicon 的 Homebrew 路径是 /opt/homebrew，压根不在默认搜索范围内。所以即使 cairo 装了，pkg-config 也找不到它的配置文件，pycairo 的构建脚本自然也就拿不到正确的头文件路径。

解决办法是手动把 Homebrew 的 pkgconfig 目录加到 PKG_CONFIG_PATH 环境变量里。Apple Silicon 机器在终端里执行：

export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:${PKG_CONFIG_PATH}"

Intel 机器执行：

export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:${PKG_CONFIG_PATH}"

然后验证一下：

pkg-config --modversion cairo

能输出版本号就说明这个环境变量起作用了。需要提醒的是，这种方式只在当前终端会话里生效。如果你关掉终端再开一个新终端，环境变量就没了。想要一劳永逸，可以把它写到 shell 配置里，比如 ~/.zshrc（macOS 默认用 zsh）：

echo 'export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:${PKG_CONFIG_PATH}"' >> ~/.zshrc source ~/.zshrc

装完 pkg-config 是另一个前提，如果你连 pkg-config 命令都没有，还得先装：

brew install pkg-config cairo

这里我实际踩过的坑是：pkg-config 的路径配置不当不仅影响 cairo，任何通过 Homebrew 安装的 C 库都可能遇到类似问题。把 /opt/homebrew/lib/pkgconfig 加入 PKG_CONFIG_PATH 是一个通用解法，它能解决一大批类似的编译报错。

2.4 一个小验证：确认三个关键文件

不管哪个系统，装完依赖之后都可以用几个命令来确认开发包是否真的就位：

最终极的验证方式还是那句pkg-config --cflags --libs cairo，它会直接输出编译和链接需要传给编译器的参数。比如 Debian 系可能输出：

-I/usr/include/cairo -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -l cairo

如果能看到这样的输出，说明 pkg-config 已经能帮你找到所有必要的编译参数，pycairo 的构建脚本也能正常工作了。

3. 依赖装齐了还报错？多半是 pkg-config 和环境变量在惹事

有时候很搞笑，明明 libcairo2-dev 装了，pkg-config 也装了，跑 pip install pycairo 还是报一样的错误。这时候问题往往不在“有没有依赖”，而在“依赖信息能不能被找到”。

3.1 pkg-config：编译器和库之间的翻译官

很多第一次处理 C 扩展编译问题的人，看到 pkg-config 这个名字会一头雾水：这不是和我没关系吗？其实关系大了。

简单的说，pkg-config 是一个查询工具，专门用来回答两个问题：某个第三方库的头文件在哪里？链接库的路径在哪里?你要用这个库来编译程序，就需要给编译器传一堆 -I 参数（头文件路径）和 -L、-l 参数（库路径和库名）。手写这些参数很痛苦，而且不同系统的路径还不一样。pkg-config 的出现就是为了让这些路径信息标准化。

pycairo 的构建脚本在准备编译时，会执行类似这样的命令：

pkg-config --cflags --libs cairo

然后拿返回值拼接出最终的编译命令。如果 pkg-config 这一步就失败了，或者找不到 cairo 的配置，构建脚本拿不到头文件路径，就会直接走回老路：默认的编译参数里没有 -I/usr/include/cairo，编译器自然找不到 cairo.h。

这个环节还牵涉到另一个常见问题：系统里有多个 pkg-config 程序。有的发行版装了多个版本，比如原版 pkg-config 和 pkgconf 可以并存。它们的默认搜索路径可能不一样，偶尔会出现一个能找到 cairo、另一个找不到的情况。遇到诡异问题时，可以用which pkg-config看看当前生效的是哪个，再用pkg-config --variable pc_path pkg-config查看当前默认搜索路径。

3.2 PKG_CONFIG_PATH：告诉工具去哪里找配置

pkg-config 的搜索路径由环境变量控制。它按顺序查找以下位置：

1. PKG_CONFIG_PATH 环境变量里指定的目录。
2. 系统默认的位置，比如 /usr/lib/pkgconfig、/usr/share/pkgconfig。

如果你想自定义某个库的配置位置，就得设置 PKG_CONFIG_PATH。macOS 的 Homebrew 场景已经说过是一个典型。再举一个案例：有些用户把 Cairo 编译安装到了自己的目录下，比如 ~/local，那就要这样设置：

export PKG_CONFIG_PATH="$HOME/local/lib/pkgconfig:${PKG_CONFIG_PATH}"

排查思路很简单：先检查 cairo.pc 文件到底放在哪个目录，然后看那个目录有没有在 PKG_CONFIG_PATH 里，没在就加进去。

我见过有人把export PKG_CONFIG_PATH=...临时加到命令行里，然后发现每次新终端都要重新设置，就以为是环境坏了。其实只是没有持久化。建议把这类设置统一写进 shell 配置文件，之后新会话也生效。

3.3 CFLAGS 和 LDFLAGS：最后一道兜底方案

还有一种极端情况：pkg-config 就是找不到，或者构建脚本没用 pkg-config，而是硬编码了某些路径（少见但存在）。这时候可以用强制指定编译参数的方式，让编译器直接知道头文件在哪、库在哪。

所谓 CFLAGS，是 C 编译器读取的环境变量，里面可以放编译期参数；LDFLAGS 是链接器读取的环境变量，放链接期参数。在安装包之前设置它们：

export CFLAGS="-I/opt/homebrew/include/cairo" export LDFLAGS="-L/opt/homebrew/lib" pip install pycairo

多个头文件路径用空格分开，里面的 -I 是告诉编译器“到这里找头文件”，-L 是“到这里找库文件”，-l 是“链接这个库”。

不过这个方法我建议优先放到最后。因为 CFLAGS 和 LDFLAGS 是全局的，你设置的参数会影响所有后续编译任务，可能引入一些意外的行为。相比起来，把 pkg-config 的路径配置好，更规范也更不容易出错。

注意：临时 export 只在当前终端会话生效。如果你在同一个终端里跑完 export 再跑 pip install，那是有效的，但关掉终端后就会消失。写进 shell 配置才是长期方案。

4. 不想碰编译链路？推几条绕开问题的路

如果你只是想要一个能用的 pycairo，而且不想折腾系统依赖，有几条路可以绕开编译这个环节。每种方案的适用场景不同，我按推荐程度分开说。

4.1 优先试试预编译 wheel

虽然 pycairo 在 Linux 上常以 sdist 形式发布，但不同版本、不同平台的情况不一样。现代 pip 在能拿到 wheel 时会优先选择 wheel，只有找不到 wheel 时才退回去找 sdist。

你可以用这个命令强制只看二进制包：

pip install --only-binary :all: pycairo

如果这个命令成功，说明当前平台有适用于你的 Python 版本和系统的 wheel。如果它报了“没有匹配的发行版本”，那就老老实实走编译路线。

这个方法的优点是干净利落，缺点也明显：能不能用完全取决于上游有没有为当前平台提供编译好的包。在老版本 pycairo 上，Linux 用户大概率会得到 No matching distribution 的回话。

4.2 用 conda 装，省掉大半烦恼

如果你已经在用 Anaconda 或 Miniconda 管理 Python 环境，那 conda 是一个很好的替代方案。

conda install -c conda-forge pycairo

conda 和 pip 最大的不同在于，conda 不只是管理 Python 包，它还管理非 Python 的依赖。conda-forge 仓库里的 pycairo 包，会自带对应版本的 cairo 库依赖，conda 会在同一个环境里把 cairo 本身也装好。你不需要动系统包管理器，也不需要关心 pkg-config，更不会遇到“系统 libcairo 版本太老”这类问题。

如果你已经有一个 conda 环境：

conda create -n myenv python=3.11 conda activate myenv conda install -c conda-forge pycairo

这种方式对新手特别友好，因为它把所有依赖都隔离在 conda 环境内部，几乎不会和系统环境冲突。

4.3 用系统包管理器直接装绑定层

Linux 发行版通常也提供了 Python 绑定包。Debian/Ubuntu 系直接装：

sudo apt install python3-cairo

Fedora/RHEL 系是：

sudo dnf install python3-pycairo

这种方式会把 pycairo 装到系统 Python 里，和 apt/dnf 的包管理生命周期绑定。好处是你完全不用操心编译问题，缺点也明显：它只对系统 Python 生效，如果你用了 virtualenv 或 venv，创建的新环境里是找不到这个包的。

还有一个坑：系统包管理器带的那版本往往比较老，跟不上 PyPI 上的最新版本。如果你对版本没有要求，只是要在系统 Python 里用 pycairo 画图，这条路径确实省事。

如果你在虚拟环境里踩到 cairo.h 的错误，记住这个核心逻辑：虚拟环境隔离的是 Python 包，隔离不了系统层的 C 库。venv 再干净，该装的系统依赖还是得装。

5. 常见问题速查与排查流程实录

这个错误在实际排查过程中会有各种变体，下表是我总结的高频情况，可以直接对照排查。

5.1 一次完整的排查过程参考

我拿一个模拟场景把整个排查流程走一遍。假设是在一台 Ubuntu 新装的服务器上操作，Python 是 3.10，执行 pip 安装时报错：

pip install pycairo ... src/importcairo.c:18:10: fatal error: cairo.h: No such file or directory

按顺序做下面几步：

第一步，确认确实是编译错误，而不是网络问题。错误的最后一行带 error: command 'gcc' failed with exit code 1，说明编译器已经被调用起来了，缺的就是头文件。

第二步，验证当前系统缺了什么：

ls /usr/include/cairo/cairo.h

返回 No such file or directory，确认机器没有 Cairo 开发头文件。

第三步，同时检查 pkg-config 是否可用：

which pkg-config

发现命令存在，但它能不能找到 cairo：

pkg-config --exists cairo && echo yes || echo no

输出 no，说明 pkg-config 也不知道这个库。

第四步，安装系统依赖：

sudo apt update sudo apt install libcairo2-dev pkg-config python3-dev

第五步，重新验证：

pkg-config --modversion cairo

输出 1.16.0，确认开发包生效。

第六步，重新安装 pycairo：

pip install pycairo

这次编译正常通过，安装完成。

这种问题虽然看起来很吓人，但把它拆成“系统有没有头文件、pkg-config 能不能找到、Python 开发头文件有没有”三个阶段，排查起来思路会非常清晰。

5.2 容易被忽略的操作细节

在实际操作过程中，有几点我常年栽过跟头，写出来给大家避雷。

关于 pip 缓存：如果你第一次安装失败，pip 可能把失败的源码包缓存下来了。重新安装时，有时候你怀疑依赖没生效，但它还是拿缓存里的旧结果在跑。加一个参数可以跳过缓存：

pip install --no-cache-dir pycairo

这个参数不解决依赖问题，但能让你的每次安装都是从干净的源码开始，排查时更可控。

关于虚拟环境：前面提过，虚拟环境只隔离 Python 包，不隔离系统库。所以不管你是用 venv、virtualenv 还是 poetry 创建的虚拟环境，系统级的 Cairo 开发包都依然需要独立安装。这是很多人入坑的根本原因。

关于 Docker 场景：如果你在 Dockerfile 里跑 pip install pycairo，别只在基础镜像里装运行时依赖，必须在同一个镜像里装开发依赖。而且构建阶段和运行阶段要拆开，多阶段构建比较合适。不把开发依赖留在最终镜像里，可以显著减小镜像体积。

5.3 一个小技巧：先把编译环境测一遍

在折腾 pycairo 之前，有一个简单的自查动作能帮你排除 80% 的问题。写一个最小的 C 文件，比如 test_cairo.c，内容就是：

#include <cairo.h> int main(void) { return 0; }

然后编译：

gcc $(pkg-config --cflags --libs cairo) test_cairo.c -o test_cairo

如果这一步能通过，说明你的编译链路是完整的，Cairo 开发库和 pkg-config 都没问题，pycairo 大概率也能顺利编译。如果这一步就挂了，那问题就在系统环境和编译配置上，先把这里修好再回头管 pycairo。

这个技巧看起来很朴素，但它把“pycairo 的问题”和“系统编译环境的问题”切分得干干净净，实战价值很高。

最后分享一点实际体会

我处理这类 C 扩展编译报错的次数多了以后，养成一个习惯：在安装任何带编译步骤的 Python 包之前，先花一分钟确认系统开发依赖是否齐全。这个习惯省下来的时间，远超我当时折腾那一晚上。

如果你遇到的是其他包的类似报错，比如fatal error: jpeglib.h对应 libjpeg-dev，fatal error: openssl/ssl.h对应 libssl-dev，思路完全一样：先定位缺失的头文件属于哪个 C 库，再用系统的包管理器装对应开发包，最后通过 pkg-config 验证能找到。这套方法论可以复制到几乎所有 C 扩展包的编译问题上。

pycairo 这个包本身不难用，难就难在第一步的依赖安装上。希望这篇文章能帮你少踩几个坑，把时间留到真正需要画图、渲染的代码上。