Docker下Python安装xhtml2pdf时reportlab报错ft2build.h缺失

故障复现 #

执行安装命令：

pip install xhtml2pdf

在Docker容器内执行上述命令时，安装流程在编译reportlab依赖阶段中断，核心报错信息如下：

!!!!! cannot find ft2build.h
error: metadata-generation-failed

报错直接原因是reportlab本地源码编译阶段找不到FreeType库对应的头文件ft2build.h，导致元数据生成失败，整个xhtml2pdf安装流程终止。

故障根因 #

pip拉取的reportlab源码包在安装时需要本地编译C扩展模块，编译过程依赖系统层面预装的FreeType、libart开发库文件，轻量级Docker镜像默认不会预装这些开发组件，直接触发编译报错。

修复步骤 #

根据容器使用的基础镜像类型，先安装对应系统依赖，再执行Python包安装即可：

• Debian/Ubuntu 系基础镜像：

  apt update && apt install -y libfreetype6-dev libart-2.0-dev
  pip install xhtml2pdf
  

• Alpine 轻量基础镜像（报错日志中出现musllinux标识即属于该类）：

  apk add --no-cache freetype-dev libart-lgpl-dev
  pip install xhtml2pdf
  

• CentOS/RHEL/Rocky Linux 系基础镜像：

  yum install -y freetype-devel libart_lgpl-devel
  pip install xhtml2pdf
  

注意：必须先完成系统依赖安装再执行pip安装命令，跳过依赖安装步骤会重复触发相同编译错误。

内容的提问来源于stack exchange，提问作者kalasagar police