PyMuPDF

环境要求

• Python 3.10 – 3.14（官方预编译 wheel 覆盖范围）
• Windows / macOS / Linux 操作系统之一
• 如需 OCR：额外安装 Tesseract 及其语言数据文件（tessdata）
• 若平台无预编译 wheel：需要 C/C++ 编译工具链

安装与启动步骤

1. 1确认 Python 版本

   PyMuPDF 为 Python 3.10–3.14 提供预编译 wheel，先确认本地版本落在此区间，避免安装时源码编译。

   python --version

   复制

2. 2安装 PyMuPDF

   README 唯一给出的安装方式，直接通过 pip 安装；无强制外部依赖，正常情况下会下载对应平台的 wheel。

   pip install pymupdf

   复制

3. 3打开 PDF 文档

   导入 pymupdf 并打开目标文件，doc 对象即文档句柄；用 page = doc[0] 取第一页做后续处理。

   python -c "import pymupdf; doc = pymupdf.open('scanned.pdf'); page = doc[0]"

   复制

4. 4OCR 识别扫描件

   对扫描版 PDF 页面调用 get_textpage_ocr，需指定 language 参数，再用 extractText() 取出识别文本。前提是 Tesseract 已安装并在 PATH 中。

   python -c "import pymupdf
   doc = pymupdf.open('scanned.pdf')
   page = doc[0]
   text = page.get_textpage_ocr(language='eng').extractText()
   print(text)"

   复制

5. 5对图片做 OCR

   OCR 可作用于独立图片：先用 Pixmap 载入图片，若带 alpha 通道必须先移除，否则无法进行 OCR。

   python -c "import pymupdf
   pix = pymupdf.Pixmap('image.png')
   if pix.alpha:
       pix = pymupdf.Pixmap(pix, 0)
   "

   复制

6. 6配置 tessdata 路径

   若未安装 Tesseract 或自动发现失败，可通过 tessdata 参数显式指定语言数据目录，或设置 TESSDATA_PREFIX 环境变量。

   export TESSDATA_PREFIX=/your/path/tessdata

   复制

关键配置

如何确认成功

执行 import pymupdf 无报错即安装成功；对扫描页调用 OCR 后能打印出识别文本即 OCR 可用。

常见问题

注意事项

• PyMuPDF 无强制外部依赖，pip install pymupdf 即可完成主体安装。
• OCR 依赖独立的 Tesseract 及其 tessdata 语言数据，需自行安装或配置路径。
• 未显式提供 tessdata 路径时，自动发现可能调用 tesseract 可执行文件（如列出可用语言）。
• 预编译 wheel 仅覆盖 Python 3.10–3.14，其他版本需源码编译。