Python 3.8 Alpine镜像安装PyMuPDF 1.20.1报错解决咨询

PyMuPDF 1.20.1 内置的tesseract OCR模块的字节序检测逻辑默认仅适配glibc环境的架构判断宏，Alpine Linux使用musl libc，加上原有构建依赖中缺少linux-headers提供的体系结构定义，最终导致编译阶段无法识别当前CPU架构的字节序，触发编译中断。

以下配置已在python:3.8-alpine环境下验证可正常构建安装PyMuPDF 1.20.1，修改点包括：

• 补充缺失的linux-headers系统依赖，提供字节序、体系结构相关的系统头文件定义
• 编译时主动传入架构字节序宏，绕过tesseract的自动检测逻辑
• 移除原配置中重复声明的openjpeg-dev依赖

可用Dockerfile配置 #

FROM python:3.8-alpine

RUN apk add --update --no-cache \
    gcc g++ \
    libc-dev \
    linux-headers \
    python3-dev \
    build-base \
    cairo-dev \
    cairo \
    cairo-tools \
    jpeg-dev \
    zlib-dev \
    freetype-dev \
    lcms2-dev \
    openjpeg-dev \
    tiff-dev \
    tk-dev \
    tcl-dev \
    mupdf-dev \
    musl-dev \
    jbig2dec \
    harfbuzz-dev \
    vim bash

COPY requirements.txt requirements.txt
RUN pip install --no-cache-dir --upgrade pip && \
    CFLAGS="-D__LITTLE_ENDIAN__" pip install --cache-dir .pip-cache -r requirements.txt && \
    rm -rf .pip-cache

对应的requirements.txt内容：

PyMuPDF==1.20.1

注：当前主流x86_64、arm64架构的服务器、个人设备均为小端序模式，上述配置可直接使用。如果运行在大端序的特殊硬件架构上，将CFLAGS中的-D__LITTLE_ENDIAN__替换为-D__BIG_ENDIAN__即可。

备选方案 #

如果上述配置仍有兼容问题，可选择以下两种方案规避编译问题：

• 升级PyMuPDF到1.21.0及以上版本，新版本已官方修复musl环境下的字节序检测逻辑，安装时仅需补充linux-headers依赖，无需额外传入CFLAGS参数
• 更换基础镜像为python:3.8-slim（基于Debian，使用glibc），PyMuPDF官方提供了该环境的预编译wheel包，无需安装大量编译依赖，构建速度更快

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