PyMuPDF 1.24.4 中文文档（一）（1）https://developer.aliyun.com/article/1559430
许可和版权
PyMuPDF 和 MuPDF 现在都提供开源的 AGPL 和商业许可证。请阅读 AGPL 许可协议的完整文本，可在发行材料（COPYING 文件）和这里找到，以确保您的使用符合许可指南。如果确定无法满足 AGPL 的要求，请联系Artifex获取有关商业许可的更多信息。
Artifex 是 MuPDF 的独家商业许可代理。
Artifex、Artifex 标志、MuPDF 和 MuPDF 标志是 Artifex Software Inc. 的注册商标。
本文档涵盖了 PyMuPDF v1.24.4 的功能，截至 2024-05-16 00:00:01。
PyMuPDF 和 MuPDF 的主要版本和次要版本将始终保持一致。只有第三个限定符（补丁级别）可能与 MuPDF 稍有不同。
对本页有任何反馈意见吗？
本软件按“现状”提供，不附带任何明示或暗示的保证。本软件根据许可分发，除非根据该许可明确授权，否则不得复制、修改或分发。有关许可信息，请参阅artifex.com或联系美国加利福尼亚州旧金山 Mesa Street 39 号 108A 室的 Artifex Software Inc. 了解更多信息。
本文档涵盖所有版本直到 1.24.4。
*
用户指南
安装：
要求：
下面的所有示例都假设您正在运行 Python 虚拟环境中。请参阅：docs.python.org/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 可用，将从 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 上
ImportError: DLL load failed while importing _fitz。
如果缺少MSVCP140.dll，可能偶尔会出现此问题，并且似乎是由某些版本（2015-2017）的Microsoft Visual C++ Redistributables中的错误引起的。
建议在msdn.com中搜索MSVCP140.dll以查找重新安装的说明。例如learn.microsoft.com/cpp/windows/latest-supported-vc-redist提供了到最新支持版本的永久链接。
更多详细信息，请参阅github.com/pymupdf/PyMuPDF/issues/2678。
注意事项：
Windows（32 位 Intel，64 位 Intel），Linux（64 位 Intel，64 位 ARM）和 Mac OSX（64 位 Intel，64 位 ARM）均提供 Wheels，在 devguide.python.org/versions/ 上标记为“Supported”的 Python 版本。
Windows 上不提供 Python 使用 Chocolatey 安装的 Wheels。而是使用来自 python.org 网站的 Windows 安装程序安装 Python，参见：www.python.org/downloads
PyMuPDF 不支持 Python 版本 3.8 之前的版本。旧版 Wheels 可在 此 仓库和 PyPI 上找到。请注意，我们通常遵循官方 Python 发布计划。对于停止官方支持的 Python 版本，这意味着将停止生成 Wheels。
没有强制要求的外部依赖项。但是，某些可选功能仅在安装了额外组件时才可用：
Pixmap.pil_save()和Pixmap.pil_tobytes()需要Pillow。Document.subset_fonts()需要fontTools。- pymupdf-fonts 是一组用于文本输出方法的漂亮字体集合。
- 用于图像和文档页面光学字符识别的Tesseract-OCR。Tesseract 是独立软件，不是 Python 包。要在 PyMuPDF 中启用 OCR 功能，必须安装该软件，并定义系统环境变量
"TESSDATA_PREFIX"并包含 Tesseract 安装位置的tessdata文件夹名称。见下文。
注意
您可以随时安装这些额外组件 - 在安装 PyMuPDF 之前或之后。PyMuPDF 将在导入时或使用相关功能时检测它们的存在。
从本地 PyMuPDF 源代码树构建和安装
初始设置：
- 按照上述方式安装 C/C++开发工具。
- 进入 Python 虚拟环境并更新 pip，如上所述。
- 获取 PyMuPDF 源代码树：
- 克隆 PyMuPDF git 仓库：
git clone https://github.com/pymupdf/PyMuPDF.git
- 或者从
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 在主版本之间可能会发生变化。
- 运行时行为可能会因为 MuPDF 不同次要版本的运行时行为而发生变化。这也可能会导致一些 PyMuPDF 测试失败。
- 如果 MuPDF 是使用其默认配置而不是 PyMuPDF 的定制配置构建的（例如，如果 MuPDF 是系统安装的），可能会导致
tests/test_textbox.py:test_textbox3()失败。可以通过在pytest命令行中添加-k 'not test_textbox3'来跳过此特定测试。
打包
参见 Linux 发行版的打包。
使用 Pyodide
参见 Pyodide。
启用集成 OCR 支持
如果您不打算使用此功能，请跳过此步骤。否则，它在安装路径和源代码两者上都是必需的 来自轮子和源代码。
PyMuPDF 已经包含了所有支持 OCR 功能所需的逻辑。但它还需要 Tesseract 的语言支持数据。
必须通过将其存储在环境变量 "TESSDATA_PREFIX" 中或作为适用函数的参数来传递语言支持文件夹位置。
因此，为了使 OCR 功能正常工作，请确保完成此检查表：
- 定位 Tesseract 的语言支持文件夹。通常情况下，你可以在这里找到它：
- Windows：
C:/Program Files/Tesseract-OCR/tessdata - Unix 系统：
/usr/share/tesseract-ocr/4.00/tessdata
- 设置环境变量
TESSDATA_PREFIX
- Windows：
setx TESSDATA_PREFIX "C:/Program Files/Tesseract-OCR/tessdata" - Unix 系统：
declare -x TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata
注
在 Windows 系统上，在启动脚本之前必须在 Python 之外完成此步骤。仅仅操作 os.environ 是不够的！
对此页面有任何反馈吗？
本软件按原样提供，不提供任何形式的保证，明示或暗示。本软件根据许可分发，未经许可不得复制、修改或分发。有关详细信息，请参阅 artifex.com，或联系美国加利福尼亚州旧金山 94129 号 Mesa Street 39 号，Artifex Software Inc.。
此文档涵盖所有版本直到 1.24.4。
要求
下面的所有示例假定您正在运行 Python 虚拟环境内。参见：docs.python.org/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 install PyMuPDF
pip install --upgrade pymupdf
如果适用于您的平台存在 Python 轮子，将从 Python 轮子安装。
在适当的轮子不可用时的安装
如果适当的 Python 轮子不可用，pip 将自动使用 Python sdist 从源代码构建。
这需要安装 C/C++ 开发工具：
- 在 Windows 上：
- 安装 Visual Studio 2019。如果未安装在标准位置，请将环境变量
PYMUPDF_SETUP_DEVENV设置为devenv.com二进制文件的位置。 - 安装其他版本的 Visual Studio，例如 Visual Studio 2022，可能会导致问题，因为 MuPDF 和 PyMuPDF 代码可能使用不同的编译器版本编译。
构建将自动下载并构建 MuPDF。
安装后出现问题
- 在 Windows 上出现
ImportError: DLL load failed while importing _fitz。
如果缺少MSVCP140.dll，有时会出现这种情况，这似乎是一些版本（2015-2017 年）的Microsoft Visual C++ Redistributables中的一个错误引起的。
建议在msdn.com中搜索MSVCP140.dll，以获取重新安装说明。例如，learn.microsoft.com/cpp/windows/latest-supported-vc-redist提供了到最新支持版本的永久链接。
查看更多详细信息，请访问github.com/pymupdf/PyMuPDF/issues/2678。
注
对于支持的 Python 版本，“支持”标志为：“Windows（32 位 Intel，64 位 Intel），Linux（64 位 Intel，64 位 ARM）和 Mac OSX（64 位 Intel，64 位 ARM）”，有 Wheels 可用，详见 devguide.python.org/versions/
在 Windows 上，使用 Chocolatey 安装的 Python 不提供 Wheels。请使用来自 python.org 网站的 Windows 安装程序安装 Python，详见：www.python.org/downloads
PyMuPDF 不支持早于 3.8 版本的 Python。旧版本 Wheels 可在 此 仓库和 PyPI 上找到。请注意，我们通常遵循官方 Python 发布计划。对于不再得到官方支持的 Python 版本，我们将停止生成 Wheels。
没有强制性的外部依赖项。但是，仅当安装了额外组件时才可用某些可选功能。
- 需要Pillow用于
Pixmap.pil_save()和Pixmap.pil_tobytes()。 - 需要fontTools用于
Document.subset_fonts()。 - pymupdf-fonts 是一组用于文本输出方法的漂亮字体集合。
- Tesseract-OCR 用于图像和文档页面的光学字符识别。Tesseract 是单独的软件，不是 Python 包。要在 PyMuPDF 中启用 OCR 功能，必须安装该软件并定义系统环境变量
"TESSDATA_PREFIX"，其值应为 Tesseract 安装位置的tessdata文件夹名称。请参阅下文。
注意
您可以随时安装这些额外的组件 - 在安装 PyMuPDF 之前或之后。PyMuPDF 在导入时或使用相关函数时会检测它们的存在。
从本地 PyMuPDF 源码树构建和安装
初始设置：
- 按照上述描述安装 C/C++ 开发工具。
- 进入 Python venv 并按上述方法更新 pip。
- 获取 PyMuPDF 源码树：
- 克隆 PyMuPDF git 仓库：
git clone https://github.com/pymupdf/PyMuPDF.git
- 或者从
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_SETUP_MUPDF_BUILD指定本地 MuPDF 树的位置构建 PyMuPDF：
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'跳过此特定测试。
使用非默认的 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 的语言支持数据。
必须通过将语言支持文件夹位置存储在环境变量"TESSDATA_PREFIX"中或作为适用函数的参数来传达。
因此，为了使 OCR 功能正常工作，请确保完成以下检查列表：
- 定位 Tesseract 的语言支持文件夹。通常您会在这里找到它：
- Windows：
C:/Program Files/Tesseract-OCR/tessdata - Unix 系统：
/usr/share/tesseract-ocr/4.00/tessdata
- 设置环境变量
TESSDATA_PREFIX
- Windows：
setx TESSDATA_PREFIX "C:/Program Files/Tesseract-OCR/tessdata" - Unix 系统：
declare -x TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata
注意
在 Windows 系统上，这必须在 Python 之外完成——在启动脚本之前。仅仅操作os.environ是不起作用的！
对此页面有任何反馈吗？
本软件按原样提供，不带任何明示或暗示的担保。本软件根据许可分发，未经许可不得复制、修改或分发。请参阅artifex.com的许可信息或联系美国加利福尼亚州旧金山市 Mesa 街 39 号 108A 套房的 Artifex Software Inc.获取更多信息。
本文档涵盖所有版本直至 1.24.4。
基础知识
打开文件
要打开文件，请执行以下操作：
import pymupdf doc = pymupdf.open("a.pdf") # open a document
注意
深入了解
请参阅 supported file types 和如何打开文件指南了解更多高级选项。
- 从 PDF 中提取文本
要从 PDF 文件中提取所有文本，请执行以下操作：
import pymupdf doc = pymupdf.open("a.pdf") # open a document out = open("output.txt", "wb") # create a text output for page in doc: # iterate the document pages text = page.get_text().encode("utf8") # get plain text (is in UTF-8) out.write(text) # write text of page out.write(bytes((12,))) # write page delimiter (form feed 0x0C) out.close()
当然，不仅 PDF 可以提取文本 - 所有 supported document file formats 如 MOBI、EPUB、TXT 等都可以提取其文本。
注意
深入了解
如果您的文档包含基于图像的文本内容，则在页面上使用 OCR 进行后续文本提取：
tp = page.get_textpage_ocr() text = page.get_text(textpage=tp)
有许多其他示例可以解释如何从特定区域提取文本或从文档中提取表格。请参阅文本操作指南。
现在您也可以以 Markdown 格式提取文本了提取文本。
API 参考
Page.get_text()
- 从 PDF 中提取图像
要从 PDF 文件中提取所有图像，请执行以下操作：
import pymupdf doc = pymupdf.open("test.pdf") # open a document for page_index in range(len(doc)): # iterate over pdf pages page = doc[page_index] # get the page image_list = page.get_images() # print the number of images found on the page if image_list: print(f"Found {len(image_list)} images on page {page_index}") else: print("No images found on page", page_index) for image_index, img in enumerate(image_list, start=1): # enumerate the image list xref = img[0] # get the XREF of the image pix = pymupdf.Pixmap(doc, xref) # create a Pixmap if pix.n - pix.alpha > 3: # CMYK: convert to RGB first pix = pymupdf.Pixmap(pymupdf.csRGB, pix) pix.save("page_%s-image_%s.png" % (page_index, image_index)) # save the image as png pix = None
注意
深入了解
有许多其他示例可以解释如何从特定区域提取文本或从文档中提取表格。请参阅文本操作指南。
API 参考
Page.get_images()- Pixmap ## 提取矢量图形
要从文档页面提取所有矢量图形，请执行以下操作：
doc = pymupdf.open("some.file") page = doc[0] paths = page.get_drawings()
这将返回在页面上找到的任何矢量图形的路径字典。
注意
深入了解
请参阅：如何提取绘图。
API 参考
Page.get_drawings()
- 合并 PDF 文件
要合并 PDF 文件，请执行以下操作：
import pymupdf doc_a = pymupdf.open("a.pdf") # open the 1st document doc_b = pymupdf.open("b.pdf") # open the 2nd document doc_a.insert_pdf(doc_b) # merge the docs doc_a.save("a+b.pdf") # save the merged document with a new filename
使用其他类型文件合并 PDF 文件
使用Document.insert_file()方法来合并 supported files 与 PDF。例如：
import pymupdf doc_a = pymupdf.open("a.pdf") # open the 1st document doc_b = pymupdf.open("b.svg") # open the 2nd document doc_a.insert_file(doc_b) # merge the docs doc_a.save("a+b.pdf") # save the merged document with a new filename
注意
深入了解
使用Document.insert_pdf() & Document.insert_file()很容易合并 PDF。通过打开的 PDF 文档，您可以从一个文档复制页面范围到另一个文档。您可以选择复制页面的位置，可以恢复页面顺序，还可以更改页面旋转。这篇维基文章包含了详细说明。
GUI 脚本join.py使用此方法合并文件列表，同时还合并了相应的目录段。看起来像这样：
API 参考
Document.insert_pdf()Document.insert_file()
PyMuPDF 1.24.4 中文文档（一）（3）https://developer.aliyun.com/article/1559433
