PyMuPDF 版本变更日志全解析：从 1.9.1 到 1.28.2 的功能演进与升级决策指南

图像处理【免费下载链接】PyMuPDFPyMuPDF is a high performance Python library for data extraction, analysis, conversion manipulation of PDF (and other) documents.项目地址https://gitcode.com/gh_mirrors/py/PyMuPDF点击查看免费下载PyMuPDF 是一套高性能的 Python 库专注于 PDF及其他格式文档的数据提取、分析、转换与操作底层基于 Artifex 的 MuPDF 引擎。本文以仓库中的权威变更记录 changes.txt被文档页 docs/changes.rst 通过.. include:: ../changes.txt直接引用为主线系统梳理从 2016 年的 1.9.1 到当前 1.28.2 的完整演进脉络重点解读每个版本的核心新增功能、破坏性变更与关键修复帮助你理解「哪个功能在哪个版本引入」「升级到新版本前需要注意什么」并为版本选型与代码迁移提供可验证的依据。说明本文所述版本号、功能引入时间与修复内容均以 changes.txt 原文为准当前仓库的构建版本定义可参见 setup.pyversion_p 1.28.2、version_mupdf 1.28.2两者一致。一、如何阅读这份变更日志结构与格式约定docs/changes.rst本体只有 5 行是一个典型的 Sphinx 组装骨架.. include:: header.rst .. include:: ../changes.txt .. include:: footer.rst真正的内容全部位于仓库根目录的 changes.txt约 3000 行。变更日志采用如下统一格式每个版本以**Changes in version X.Y.Z** (日期)开头随后列出本版本对应的MuPDF 基础版本例如 1.28.2 使用 MuPDF-1.28.2Fixed issues:小节列出修复的 GitHub issue 编号如#5112Other:小节列出新增 API、行为变化、构建与分发调整文档内通过.. codespell:ignore-begin/.. codespell:ignore-end包裹历史遗留的旧式命名记录以便拼写检查工具跳过。阅读建议若你关心「某 API 何时出现」直接在 changes.txt 中搜索该 API 名称若关心「某 issue 何时修复」搜索其编号即可。变更日志中大量使用**Fixed** 编号形式编号同时附带原始 GitHub issue 链接本文按仓库规范不输出外部链接仅保留编号便于对照。二、近一年核心版本1.26.0 → 1.28.2 的功能主线最近几个版本是 PyMuPDF 现代化重构的集中体现也是升级用户最需要关注的区间。2.1 1.28.22026-08-06表单层级、确定性与安全加固表单Form能力大幅增强新增对表单字段层级form field hierarchies、单选按钮组radio button groups与字段别名widget aliases的支持确定性输出Document.save()新增reproducible/deterministic输出选项issue #5056可省略 MuPDF 版本横幅与 Producer 信息便于生成可复现文件Page.find_tables()参数扩展新增use_layout: bool True、union: bool False、refine: bool False三个参数并显著提升速度fitz兼容层弃用警告导入旧名fitz模块时改为通过warnings.warn()发出FutureWarning替代此前直接向控制台打印的做法分发扩展新增 windows-arm64 wheel支持PYMUPDF_SETUP_MUPDF_VS_UPGRADE构建选项重要修复修复clean_contents(sanitizeTrue)丢失字形定位的回归#5054、Page.remove_rotation()在 90°/270° 旋转页上导致注释消失或位移#5059、get_texttrace()在长运行进程中的None引用泄漏#5042、字体子集化段错误#5049等。2.2 1.28.02026-06-29Archive 参数、CSS 应用与跨格式保存pymupdf.Document.__init__()新增archive参数支持直接以压缩包形式打开文档Document.convert_to_pdf()现在同时生成链接Document.save()支持将非 PDF 文档直接保存为 PDF 格式新增Document.apply_css()方法Pyodide wheel 正式发布到 PyPI修复了表单公式渲染为黑块#5001、矢量图形线条画不完全涂黑#4936、write_images()配合garbage1保存破坏字体 xref#4896等问题。2.3 1.27.x2026-02 ~ 2026-04OCR 全面化与文本裁剪常量1.27.2 起对get_textpage_ocr()做了重要改进部分 OCR 现在覆盖页面全部非可读文本区域包括矢量图形与含不可识别字符的文本而不再局限于图片内部#3842。1.27.1 新增了pymupdf.TEXT_CLIP常量、Document.save()的raise_on_repair参数与Document.repair()方法并移除对 MuPDF 1.26 的支持。2.4 1.26.x2025-05 ~ 2025-12重写图像、页面裁剪与表单元数据Document.rewrite_images()1.26.1 新增用于减小文件体积、转换图片格式或转换色彩空间Page.clip_to_rect()1.26.4 新增将页面裁剪到指定矩形Page.get_image_info()与get_drawings()持续修复缓存与属性解析问题Shape类正式公开为pymupdf.Shape1.26.3并移除了pymupdf.utils.Shape重复定义1.26.5表格模块1.26.3新增表格单元格 Markdown 输出支持1.26.6 起支持的 Python 版本为 3.10–3.141.26.5 时为 3.9–3.14。2.5 1.25.x2024-12 ~ 2025-03注释富文本、表单字段与 span 字典增强FreeText 注释新增FreeTextCallout子类型与富文本rich text支持1.25.3insert_text*()系列新增miter_limit参数用于抑制长斜接产生的尖刺spikesDocument.insert_pdf()支持复制 Widget表单字段span 字典新增bibi键char 字典新增synthetic键span 字典还新增char_flags成员可检测不可见文本Pixmap.pil_image()新增1.25.2直接返回 Pillow Image 对象。三、表格识别Table Detection功能的演进表格识别是 PyMuPDF 近年持续投入的功能其演进脉络贯穿 1.23.x 与 1.24.x源码实现在仓库的 src/table.py 及 src/_table_headers.py、src/_table_refine.py、src/_table_spans.py、src/_table_union.py 等模块中测试见 tests/test_tables.py。1.23.0Page.find_tables()首次引入可在任意受支持文档页上定位表格并按单元格提取内容1.23.13修复to_pandas()的list index out of range#2979以及对一个文档调用find_tables()改变后续文档 bbox 的串扰问题#30011.23.16lines_strict策略排除纯填充的矢量图形1.23.19允许在查表时加入用户自定义的虚拟矢量图形并加速矩形相交判断1.23.24修复垂直文本处理#3148与矢量图形簇的错误分离#31791.24.0新增将表格输出为 Markdown 字符串的方法修复表头对象计算错误允许None单元格值在 pandas DataFrame 场景按需解析并正确纳入线条起止点以计算簇包围盒1.28.2find_tables()新增use_layout、union、refine三个参数并修复启用 layout 时返回零单元格表格导致Table.bbox抛ValueError的问题#5030。从源码结构看表格模块被拆分为多个职责单一的文件_table_headers表头识别、_table_refine表格细化、_table_spans单元格跨度、_table_union表格合并共同支撑Page.find_tables()的完整流程。四、API 命名体系的重构camelCase → snake_case 与 fitz → pymupdf变更日志中最具影响力的演进之一是 API 命名与模块名的两次大迁移直接影响所有存量代码。4.1 命名风格迁移1.18.x 起1.18.3以Annot类为试点启动将 camelCase/mixedCase 命名的属性和方法转换为lower_case_with_underscores风格的长期工程旧名称继续保留以避免代码破坏但不再出现在文档中1.18.14snake_case 命名基本完成文档末尾新增 Deprecated 章节提供新旧名称映射表迁移示例Page.getText→Page.get_text、Page.searchFor→Page.search_for、Document.save不变、Pixmap.getPNGdata→Pixmap.tobytes别名等。4.2 模块名迁移fitz → pymupdf1.24.31.24.3Python 模块正式更名为pymupdffitz仍作为向后兼容别名保留1.28.2 起导入旧名fitz会输出警告且使用warnings.warn()FutureWarning此前 1.28.0 开始为控制台打印对应地1.24.2 从发行版中移除了旧的 classic 实现fitz_old模块。4.3 底层实现的重写classic → rebased1.23.x1.23.0引入全新的 rebased 实现作为fitz_new模块提供可import fitz_new as fitz直接替换同时把与 Python 无关的 MuPDF 库拆分到独立的PyMuPDFbwheel1.23.9默认切换到 rebased 实现旧 classic 实现通过import fitz_old as fitz保留rebased 实现改进了类型标注1.26.5 起所有类方法显式定义不再动态赋值、去除了(*args, **kwargs)式的 API 签名1.23.8、并支持 MuPDF 新的 Python 异常类1.24.2 起 classic 实现从发行版移除。五、文本提取与搜索的核心能力演进文本提取是 PyMuPDF 最常用的能力其 API 与内部行为在多个版本中持续增强1.16.3get_text()的 dict/rawdict 变体移植到 C 实现文本型文档上速度接近翻倍1.18.2文本搜索支持任意数量的命中结果移除hit_max参数、新增clip参数限定搜索区域、支持跨行断词连字符检测1.19.1get_text()支持sort参数输出按标准阅读顺序左上→右下排序1.19.2文本搜索与提取默认开启TEXT_MEDIABOX_CLIP标志自动抑制完全位于页面 MediaBox 之外的字符不再需要手动传clippage.rect1.22.0行为变化——文本提取现在包含与 clip 矩形重叠的字形此前仅包含完全位于 clip 内的字形1.23.5支持额外的词分隔符extra word delimiters1.24.14确保get_text()返回的 words 不混入 RTL/LTR 字符1.19.0 起新增get_texttrace()低层字符属性含 sequence number 指示页面绘制顺序与get_bboxlog()返回页面对象矩形列表序列顺序可判断对象遮挡关系。文本提取的 flags 体系变更日志多次提及TEXT_*系列 flags如TEXT_MEDIABOX_CLIP、TEXT_INHIBIT_SPACES。1.19.6 还新增了便捷常量TEXTFLAGS_WORDS对应get_text(words)等默认标志组合。这些常量的具体位定义可查阅 docs/textpage.rst 中的文本提取标志章节。六、OCRTesseract 集成能力演进PyMuPDF 从 1.19.0 开始集成 Tesseract OCR该能力源自 MuPDF 1.18.01.19.0OCR 功能正式落地——Pixmap.pdfocr_save()/pdfocr_tobytes()生成带 OCR 文本层的单页 PDFPage.get_textpage_ocr()对页面执行 OCR 并把结果与常规内容合并进TextPage文本搜索/提取方法新增textpage参数以复用已创建的 TextPage依赖说明OCR 需要独立安装 TesseractMuPDF 仅需要其tessdata文件夹路径通过环境变量TESSDATA_PREFIX提供1.19.1get_textpage_ocr()新增dpi参数控制 OCR 质量并可选择整页 OCR 或仅 OCR 页面显示的图片1.22.5新增get_tessdata()函数定位 Tesseract 语言包目录OCR 函数支持tessdata参数1.27.2部分 OCR 覆盖范围从图片内扩展到页面全部非可读文本区域矢量图形、含不可识别字符的文本。仓库相关测试见 tests/test_tesseract.py文档见 docs/recipes-ocr.rst 与 docs/ocr/tesseract-language-packs.rst。七、内容编辑、净化与信息安全7.1 涂黑Redaction1.16.11新增Page.add_redact_annot()与Page.apply_redactions()支持涂黑删除文本1.16.12增强——被涂黑矩形包含的图片与 XObject 会被移除部分重叠则被背景色覆盖可指定 overlay 文本插入矩形区域1.17.0与涂黑重叠的图片被永久擦除重叠区域重叠链接被移除与 PDF 规范完全同步1.24.0支持涂黑矢量图形1.28.0修复矢量线条画涂黑不完整#4936。7.2 净化Scrub与流处理1.16.14新增Document.scrub()移除 PDF 中的潜在敏感数据1.18.10 加固了 JavaScript 对象移除1.18.7 新增thumbnails参数以同时删除页面缩略图1.18.2 新增redact_images选项1.27.1Document.save()新增raise_on_repair参数、新增Document.repair()1.24.1Document.save()/ez_save()/write()新增use_objstm、compression_effort、preserve_metadata参数1.24.10 起对象流与线性化linearization不能同时使用尝试同时启用会抛出异常#3603而 1.26.0 起完全移除了 PDF 线性化支持save(linearTrue)将抛异常。八、PDF 生成、表单字段与低层对象操作8.1 表单字段Widgets1.13.2PDF 表单支持起步——Document.is_form_pdf、Annot.widget_type等属性1.13.11可添加 Text、CheckBox、ListBox、ComboBox 四种表单字段1.13.12Annot.update_widget()支持修改已有字段含字段值ListBox/ComboBox 可选值列表统一为Widget.choice_values1.25.3Document.insert_pdf()支持复制 Widget1.22.x修复了单选按钮组的状态同步问题#2333、#23911.28.2支持表单字段层级、单选按钮组与字段别名变更日志特别提醒1.16.0 起注释annotations与表单字段widgets是两条独立的对象链——Page.first_annot/Annot.next不会再遍历到 widget必须使用Page.first_widget/Widget.next。8.2 PDF 生成1.11.0Document.insert_page()含文本、Page.insert_image()、Page.insert_text()奠定 PDF 内容生成基础1.11.1Shape类引入统一页面绘图 API1.22.0新增/PageMode、/PageLayout、/MarkInfo的 getter/setter、Document.version_count增量保存次数 1、is_fast_webaccess是否线性化等属性1.24.2Document.bake()把注释/字段固化为永久内容Page.cluster_drawings()按几何邻近度聚类矢量图形apply_redactions()新增text参数。8.3 低层 xref 操作从 1.16.8 起提供Document.xref_object、xref_stream、xref_stream_raw、pdf_trailer、pdf_catalog、update_object、update_stream等系列方法1.18.7 新增xref_get_keys/xref_get_key/xref_set_key1.18.10 起支持用-1访问 trailer 字典1.19.5 新增Document.xref_copy。相关方法文档集中在 docs/document.rst 与 docs/lowlevel.rst。九、打印、渲染与图片处理Pixmap 渲染1.16.0 起Page.get_pixmap()/Annot.get_pixmap()支持annots参数抑制注释渲染1.19.2 起支持dpi参数此时matrix被忽略1.10.0 起 alpha 通道可选显著减小像素图体积CMYK -20%、RGB -25%、GRAY -50%图片提取extract_image()自 1.14.9 起对 JPX 图片返回原始格式避免转 PNG 导致的体积剧增Page.get_image_bbox()/get_image_rects()持续改进1.17.5 新增Page.get_svg_image()的text_as_path选项生成更小的 SVG颜色1.14.12 起绘图与文本插入支持 GRAY/CMYK 色彩空间1.19.1 起get_drawings()/get_cdrawings()自动将颜色转为 RGB 元组抗锯齿1.16.14 起Tools.set_aa_level()可控制抗锯齿级别。十、安全与稳定性内存泄漏、崩溃与资源问题修复趋势变更日志中占比最高的是内存泄漏、段错误segfault与资源管理修复这反映 PyMuPDF 与 MuPDF 底层 C 代码交互的复杂性内存泄漏insert_pdf()#1417/#1418、#3201、1.18.0 修复 #669、get_text(rawdict)#362/#290、extract_blocks的文本对象引用#5067、widgets()迭代#4751等均有针对性修复段错误apply_redactions()与透明图片重叠#1824、get_drawings()#1971、subset_fonts()字体子集化#5049、Pillow 混用#4762等资源管理1.13.19 起 Python 3 构建全程使用 Python 内存管理替代原生malloc()1.24.6 修复了并发使用时的临时文件名冲突防御性增强1.23.0 起对/Annots数组中的非法成员null、非字典项跳过处理1.18.1 起检测并恢复页面资源循环依赖。从仓库结构看tests/目录中存在大量以 issue 编号命名的回归测试如 tests/test_5044.py、tests/test_4942.py、tests/test_4670.py 等与变更日志中对应编号一一呼应可作为该修复确有回归测试覆盖的佐证。十一、Python 版本支持与构建分发演进Python 支持范围1.23.0 放弃 Python-3.71.24.12 放弃 3.8、新增 3.13当时支持 3.9–3.131.26.5 支持 3.9–3.141.26.6 起为 3.10–3.14最新变更还提到适配 Python-3.15 预发布版与 free-threading自由线程PythonWheel 策略1.24.11 起 wheel 使用 Python Stable ABI——每个平台一个 wheel兼容所有受支持的 Python 版本且不再有独立的 PyMuPDFb wheel1.28.2 新增 windows-arm64 wheel1.24.6 起增加 musllinux x86_64 wheel构建系统1.22.0 引入pyproject.toml1.20.0 起从 sdist 构建时自动下载并编译所需 MuPDF 源码无需预装 MuPDF1.23.26 起 sdist 不再包含 MuPDF 源码构建时自动下载版本信息属性1.24.6 起提供pymupdf.pymupdf_version、pymupdf.mupdf_version、pymupdf.pymupdf_date1.23.7 起提供fitz.pymupdf_version_tuple如(1, 23, 6)1.26.1 起pymupdf_date与VersionDate不再随版本填充均为 None且版本号不再携带发布日期。十二、升级与迁移检查清单综合变更日志中的破坏性变更Breaking Changes升级到新版前建议逐一核对模块导入import fitz仍可用但会告警1.28.2 起为FutureWarning新代码请使用import pymupdf命名风格camelCase 旧方法如getText、searchFor已不再出现在文档中新代码应使用 snake_case 形式get_text、search_for线性化Document.save(linearTrue)自 1.26.0 起直接抛异常线性化支持已移除对象流 线性化组合自 1.24.10 起即被禁止保存行为Document.save()自 1.28.0 起可保存非 PDF 文档为 PDF需要可复现输出时使用 1.28.2 的确定性保存选项注释与表单分离遍历注释不会经过表单字段表单字段需走first_widget链OCR 依赖OCR 功能需要独立安装 Tesseract 并配置TESSDATA_PREFIXPython 版本确认你的 Python 版本在支持范围内当前为 3.10–3.14剪贴行为1.22.0 起文本提取对 clip 矩形的包含规则从完全包含变为重叠即包含涉及精确坐标计算的场景需复核。十三、如何验证与进一步阅读对照源码changes.txt 提到的 API 大多能在 src/pymupdf.py、src/fitz_table.py、src/fitz_utils.py 中找到实现构建与版本定义见 setup.py对照测试tests/目录下以 issue 编号命名的测试文件如 tests/test_5044.py、tests/test_5044.py 等直接对应变更日志中的修复项安装方式pip install pymupdf即可从源码构建时 sdist 会自动下载对应 MuPDF 版本配套文档各功能的详细 API 说明分散于 docs/document.rst、docs/page.rst、docs/annot.rst、docs/textpage.rst、docs/pixmap.rst 等文件变更日志可视为这些文档的时间轴索引。结语从 2016 年的 1.9.1 到 2026 年的 1.28.2PyMuPDF 走过了从PDF 文本提取工具到覆盖提取、分析、转换、生成与安全处理的完整文档处理平台的演进之路。这份变更日志既是版本索引也是理解库设计决策命名迁移、实现重写、功能取舍的第一手资料。升级时以本文第十二节的检查清单为依据结合 changes.txt 中对应版本段的原文即可做出稳妥的迁移决策。赞分享图像处理【免费下载链接】PyMuPDFPyMuPDF is a high performance Python library for data extraction, analysis, conversion manipulation of PDF (and other) documents.项目地址https://gitcode.com/gh_mirrors/py/PyMuPDF点击查看免费下载相关推荐Slint 变更日志全解读从 0.0.1 到 1.18.0 的功能演进与升级迁移指南Slint 变更日志全解读从 0.0.1 到 1.18.0 的功能演进与升级迁移指南 本文以 CHANGELOG.md https://link.gitcod前端UI组件桌面应用嵌入式移动开发跨平台Apache Airflow Airbyte Provider 版本演进全解读从 1.0.0 到 6.0.1 的变更日志与升级实战指南Apache Airflow Airbyte Provider 版本演进全解读从 1.0.0 到 6.0.1 的变更日志与升级实战指南 Apache Airf后端任务调度工作流自动化数据编排批处理数据工程流程编排OpenArkWindows内核级安全分析工具的终极指南OpenArkWindows内核级安全分析工具的终极指南 在Windows系统安全领域反Rootkit工具一直是安全专家和逆向工程师的必备利器。OpenAr应用安全网络安全逆向工程内核驱动桌面应用系统编程上一篇Spek频谱分析器新手教程安装、使用与参数调节完整指南下一篇不打开完整Office就能预览Word、Excel、PPTQuickLook Office原生预览插件使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考