安装#

要求#

下面所有的示例都假设你正在 Python 虚拟环境中运行。详情请参阅：https://docs.pythonlang.cn/3/library/venv.html。我们还假设 pip 已是最新版本。

例如

Windows

py -m venv pymupdf-venv
.\pymupdf-venv\Scripts\activate
python -m pip install --upgrade pip

Linux, MacOS

python -m venv pymupdf-venv
. pymupdf-venv/bin/activate
python -m pip install --upgrade pip

安装#

PyMuPDF 应该使用 pip 安装，命令如下：

pip install --upgrade pymupdf

如果你的平台有可用的 Python wheel 包，这将从 wheel 包安装。

没有合适的 wheel 包时的安装#

如果没有合适的 Python wheel 包可用，pip 将自动使用 Python sdist 从源代码构建。

这需要安装 C/C++ 开发工具:

在 Windows 上
- 安装 Visual Studio 2019。如果未安装在标准位置，请将环境变量 PYMUPDF_SETUP_DEVENV 设置为 devenv.com 二进制文件的位置。
- 安装其他版本的 Visual Studio，例如 Visual Studio 2022，可能会导致问题，因为 MuPDF 和 PyMuPDF 代码可能使用不同的编译器版本进行编译。

构建过程将自动下载并构建 MuPDF。

安装后的问题#

在 Windows 上，Python 错误
```
ImportError: DLL load failed while importing _extra
```
如果缺少 MSVCP140.dll，有时会看到此错误，这似乎是由某些版本（2015-2017）的 Microsoft Visual C++ Redistributables 中的 bug 引起的。

建议在 https://msdn.com 中搜索 MSVCP140.dll，查找如何重新安装的说明。例如 https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist 提供了指向最新支持版本的永久链接。

更多详情请参阅 https://github.com/pymupdf/PyMuPDF/issues/2678。
Python 错误
```
ModuleNotFoundError: No module named 'frontend'
```
如果使用了 PyMuPDF 的旧名称 fitz（例如 import fitz 而非 import pymupdf），并且安装了无关的名为 fitz 的 Python 包（https://pypi.ac.cn/project/fitz/），则可能发生此问题。

fitz 包似乎不再维护（最新版本是 2017 年的），但不幸的是，它似乎无法从 pypi.org 中移除。它本身甚至无法工作，并且会破坏 PyMuPDF 旧名称的使用。

有几种方法可以避免此问题
- 使用 import pymupdf 而非 import fitz，并相应地更新代码。
- 或者卸载 fitz 包并重新安装 PyMuPDF
```
pip uninstall fitz
pip install --force-reinstall pymupdf
```
- 或者使用 import pymupdf as fitz。但这尚未经过充分测试。
在 Apple Silicon (arm64) 上的 Jupyter labs 中，Python 错误
```
ImportError: /opt/conda/lib/python3.11/site-packages/pymupdf/libmupdf.so.24.4: undefined symbol: fz_pclm_write_options_usage
```
这似乎是 Jupyter labs 中的一个问题；详情请参阅：https://github.com/pymupdf/PyMuPDF/issues/3643#issuecomment-2210588778。
在 Windows 上，Python 错误
```
ImportError: dynamic module does not define module export function (PyInit__extra)
```
此问题于 2025 年 3 月 26 日在 https://github.com/pymupdf/PyMuPDF/issues/4405 中报告。

修复方法似乎是安装最新的 VC_redist.x64.exe。

注意事项#

以下平台提供了 wheel 包：
- Windows 32 位 Intel。
- Windows 64 位 Intel。
- Linux 64 位 Intel。
- Linux 64 位 ARM。
- MacOS 64 位 Intel。
- MacOS 64 位 ARM。
详情
- 我们为上述每个平台发布一个单独的 wheel 包。
- 每个 wheel 包都使用当前支持的最早 Python 版本（目前是 3.9）的 Python Stable ABI，因此适用于所有后续 Python 版本，包括新的 Python 版本。
- Wheel 包已在 https://devguide.pythonlang.cn/versions/ 当前标记为“Supported”（支持）的所有 Python 版本上进行了测试，目前包括 3.9、3.10、3.11、3.12 和 3.13。
使用 Chocolatey 在 Windows 上安装的 Python 不提供 wheel 包。请改用 python.org 网站提供的 Windows 安装程序来安装 Python，请参阅：https://pythonlang.cn/downloads
对于使用 Musl libc 的 Linux-aarch64（例如 aarch64 上的 Alpine Linux），不提供 wheel 包，且已知从源代码构建会失败。
没有强制性的外部依赖项。但是，某些可选功能只有在安装了额外组件后才可用：
- Pillow 是 Pixmap.pil_save() 和 Pixmap.pil_tobytes() 所必需的。
- fontTools 是 Document.subset_fonts() 所必需的。
- pymupdf-fonts 是一系列不错的字体，可用于文本输出方法。
- Tesseract-OCR 用于图像和文档页面中的光学字符识别。Tesseract 是独立的软件，不是 Python 包。要在 PyMuPDF 中启用 OCR 功能，必须安装 Tesseract 并指定 tessdata 文件夹名称；参见下文。
注意

你可以随时安装这些额外的组件——在安装 PyMuPDF 之前或之后。PyMuPDF 会在导入时或使用相关功能时检测它们是否存在。

从本地 PyMuPDF 源代码树构建和安装#

初始设置

按照上述说明安装 C/C++ 开发工具。
进入一个 Python 虚拟环境并更新 pip，如上所述。
获取 PyMuPDF 源代码树
- 克隆 PyMuPDF git 仓库
```
git clone https://github.com/pymupdf/PyMuPDF.git
```
- 或从 https://github.com/pymupdf/PyMuPDF/releases 下载并解压 .zip 或 .tar.gz 源代码版本。

然后可以通过两种方式构建 PyMuPDF：

使用默认 MuPDF 版本构建并安装 PyMuPDF
```
cd PyMuPDF && pip install .
```
这将自动下载特定的硬编码 MuPDF 源代码版本，并将其构建到 PyMuPDF 中。
或者使用本地 MuPDF 源代码树构建并安装 PyMuPDF
- 克隆 MuPDF git 仓库
```
git clone --recursive https://git.ghostscript.com/mupdf.git
```
- 构建 PyMuPDF，使用环境变量 PYMUPDF_SETUP_MUPDF_BUILD 指定本地 MuPDF 树的位置
```
cd PyMuPDF && PYMUPDF_SETUP_MUPDF_BUILD=../mupdf pip install .
```

另外，可以在同一个 PyMuPDF 树中为不同的 Python 版本构建

PyMuPDF 将为运行 pip 所使用的 Python 版本进行构建。要使用特定 Python 版本运行 pip，请使用 python -m pip 而非 pip。

例如，在 Windows 上可以使用以下命令构建不同版本：
```
cd PyMuPDF && py -3.9 -m pip install .
```
或
```
cd PyMuPDF && py -3.10-32 -m pip install .
```

运行测试#

拥有 PyMuPDF 源代码树后，即可运行 PyMuPDF 的 pytest 测试套件

pip install pytest fontTools
pytest PyMuPDF/tests

关于使用非默认 MuPDF 的注意事项#

通过设置环境变量 PYMUPDF_SETUP_MUPDF_BUILD 使用非默认构建的 MuPDF 可能会导致各种问题，因此通常不被支持

如果 MuPDF 的主版本号与 PyMuPDF 默认使用的版本号不同，PyMuPDF 可能会构建失败，因为 MuPDF 的 API 在不同主版本之间可能会发生变化。
PyMuPDF 的运行时行为可能会发生变化，因为 MuPDF 的运行时行为在不同次要版本之间会发生变化。这也可能导致某些 PyMuPDF 测试失败。
如果 MuPDF 是使用其默认配置而不是 PyMuPDF 的自定义配置构建的（例如，MuPDF 是系统安装的），则 tests/test_textbox.py:test_textbox3() 可能会失败。可以通过向 pytest 命令行添加 -k 'not test_textbox3' 来跳过此特定测试。

打包#

请参阅为 Linux 发行版打包。

与 Pyodide 一起使用#

请参阅 Pyodide。

启用集成 OCR 支持#

如果你不需要使用此功能，请跳过此步骤。否则，无论采用哪种安装方式：从 wheel 包安装还是从源代码安装，都需要此步骤。

PyMuPDF 本身已经包含了支持 OCR 功能所需的所有逻辑。但它额外还需要 Tesseract 的语言支持数据。

如果未明确指定，PyMuPDF 将尝试查找已安装 Tesseract 的 tessdata，但这可能不应该依赖。

否则，PyMuPDF 要求在 PyMuPDF OCR 函数的 tessdata 参数中或在 os.environ["TESSDATA_PREFIX"] 中明确指定 Tesseract 的语言支持文件夹。

因此，为了使 OCR 功能正常工作，请确保完成以下清单：

找到 Tesseract 的语言支持文件夹。通常可以在这里找到：
- Windows: C:/Program Files/Tesseract-OCR/tessdata
- Unix 系统: /usr/share/tesseract-ocr/4.00/tessdata
调用 PyMuPDF OCR 函数时指定语言支持文件夹
- 设置 tessdata 参数。
- 或者在 Python 中设置 os.environ["TESSDATA_PREFIX"]。
- 或者在运行 Python 之前设置环境变量 TESSDATA_PREFIX，例如：
  - Windows: setx TESSDATA_PREFIX "C:/Program Files/Tesseract-OCR/tessdata"
  - Unix 系统: declare -x TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata

本软件“按原样”提供，不附带任何明示或暗示的保证。本软件根据许可证分发，未经该许可证条款明确授权，不得复制、修改或分发。有关许可信息，请参阅 artifex.com 或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States 获取更多信息。