安装#

需求#

以下所有示例假设您在 Python 虚拟环境中运行。有关详细信息，请参见：https://docs.python.org/3/library/venv.html。我们还假设 pip 是最新的。

例如：

窗口：

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

安装#

应使用pip安装PyMuPDF：

pip install --upgrade pymupdf

如果您的平台有可用的Python 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 _fitz
```
如果缺少 MSVCP140.dll，则偶尔会看到这种情况，并且似乎是由某些版本（2015-2017）中的一个错误引起的 Microsoft Visual C++ Redistributables。

建议在 MSVCP140.dll 上搜索 https://msdn.com 以找到如何重新安装它的说明。例如 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），并且安装了一个不相关的Python包 fitz (https://pypi.org/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。然而，这尚未经过充分测试。
在苹果硅（arm64）上的Jupyter实验室，Python错误：
```
ImportError: /opt/conda/lib/python3.11/site-packages/pymupdf/libmupdf.so.24.4: undefined symbol: fz_pclm_write_options_usage
```
这似乎是Jupyter实验室中的一个问题；请参见： https://github.com/pymupdf/PyMuPDF/issues/3643#issuecomment-2210588778.

注意#

以下平台提供轮子：
- Windows 32位英特尔。
- Windows 64位英特尔。
- Linux 64位英特尔。
- Linux 64位 ARM。
- MacOS 64位 Intel.
- MacOS 64位 ARM。
详情：
- 我们为上述每个平台发布一个单一的轮子。
- 每个轮子使用当前最旧支持的 Python 版本（当前为 3.9）的 Python 稳定 ABI，因此可以与所有后续的 Python 版本兼容，包括新的 Python 版本。
- 轮子在所有当前标记为“受支持”的Python版本上进行测试， https://devguide.python.org/versions/，目前是3.9、3.10、3.11、3.12和3.13。
在Windows上使用Chocolatey安装的Python不支持轮子（wheels）。请改为使用python.org网站上的Windows安装程序安装Python，详情请参见：http://www.python.org/downloads
在 Linux-aarch64 系统上，使用 Musl libc（例如在 aarch64 上的 Alpine Linux）时，不提供轮子，并且已知从源代码构建会失败。
没有强制的外部依赖关系。然而，某些可选功能仅在安装了附加组件时可用：
- 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
```
- 或者从 .zip 或 .tar.gz 源代码发布中下载并提取，链接为 https://github.com/pymupdf/PyMuPDF/releases。

然后可以通过两种方式构建 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支持#

如果您不打算使用此功能，请跳过此步骤。否则，对于两种安装路径都是必需的：从轮子和从源代码。

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

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

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

因此，对于一个有效的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

Do you have any feedback on this page?

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