Docker环境中PyMuPdf（fitz）模块导入失败求助

问题重现 #

本地Windows环境中import fitz正常运行，Docker构建镜像时已通过requirements.txt或pip install pymupdf安装PyMuPDF，但运行容器时抛出：

File "/code/table.py", line 35, in <module>
    import fitz
ModuleNotFoundError: No module named 'fitz'

排查与解决方案 #

1. 对齐Python版本与依赖版本 #

• 确保Docker基础镜像的Python版本和本地一致（比如本地用Python3.9，Docker就用python:3.9-slim），PyMuPDF对不同Python版本的兼容可能存在差异。
• 在requirements.txt中指定和本地完全一致的PyMuPDF版本（本地执行pip show PyMuPDF查看版本），避免自动安装最新版导致兼容问题：

  PyMuPDF==1.23.10  # 替换成你本地的版本号
  

2. 修正Dockerfile构建顺序 #

Dockerfile的构建顺序会影响缓存和依赖安装有效性，正确顺序应该是先装依赖再复制代码：

FROM python:3.9-slim  # 匹配本地Python版本
WORKDIR /code

# 先复制依赖文件，利用Docker缓存
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# 最后复制项目代码
COPY . .

CMD ["python", "table.py"]

注意：不要先复制代码再安装依赖，否则修改代码会触发重新安装依赖，且可能因缓存导致依赖未正确更新。

3. 检查卷挂载的干扰 #

如果docker-compose中挂载了本地目录到容器的/code：

• 确保本地项目目录中没有名为fitz的文件夹或fitz.py文件，否则会覆盖PyMuPDF的官方包。
• 不要挂载本地的虚拟环境（如venv）到容器，Docker容器内直接使用系统Python环境即可。

4. 验证容器内的依赖安装状态 #

进入运行中的容器，手动验证PyMuPDF是否安装成功：

# 替换成你的容器名称或ID
docker exec -it <container-name> bash

# 在容器内执行Python导入测试
python -c "import fitz; print(fitz.__version__)"

如果仍报错，说明镜像构建时依赖未正确安装，重新构建镜像并查看pip install的日志，确认没有安装失败的提示（如网络问题导致下载中断）。

5. 避免pip安装的大小写问题 #

虽然pip不区分包名大小写，但明确使用大写的PyMuPDF进行安装更稳妥，在Dockerfile中可以单独指定：

RUN pip install --no-cache-dir PyMuPDF==1.23.10

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