如何用 pypdf 完成 PDF 合并、拆分与文本提取？完整指南

如何用 pypdf 完成 PDF 合并、拆分与文本提取？完整指南

【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf

pypdf 是一个纯 Python 实现的 PDF 处理库，核心功能是合并、拆分、裁剪和变换 PDF 页面，同时支持加密解密、元数据读取和文本提取。它解决的核心问题是：不依赖 Adobe 等商业软件，用几行脚本就能批量、可重复地处理 PDF 文件。当前仓库版本为 6.18.1，基于 BSD-3-Clause 协议开源。

核心能力速览：

快速开始：安装 pypdf 并运行第一个脚本

pypdf 要求 Python 3.9 及以上，核心安装只需一条命令（需要 AES 加解密时安装pip install pypdf[crypto]）：

pip install pypdf

最小可运行示例（假设当前目录有一份 example.pdf，可替换为你手头的任意 PDF）：

from pypdf import PdfReader reader = PdfReader("example.pdf") print("页数:", len(reader.pages)) print("首页文本:", reader.pages[0].extract_text()[:80])

成功的标志：终端先输出一行页数（如页数: 4），随后打印出首页开头约 80 个字符的文本。能打印出真实文字内容，说明安装与文本提取都正常。

核心功能详解

pypdf 提取文本：按页读取并输出

适合需要从合同、报告中批量取文本做检索或汇总的场景。

from pypdf import PdfReader reader = PdfReader("example.pdf") for i, page in enumerate(reader.pages): print(f"--- 第{i+1}页 ---") print(page.extract_text())

效果提示：extract_text()支持传入角度元组（如(0, 90)）只取特定方向的文字，也支持extraction_mode="layout"尽量还原版面布局。坑点：扫描件或纯图片 PDF 没有文字层，提取结果为空，需要 OCR，pypdf 不做 OCR。

pypdf 合并 PDF：多文件拼接成一份

适合把多份周报、附件合并成单一文件，也适合从一个 PDF 中按页拆分。

from pypdf import PdfWriter writer = PdfWriter() for pdf in ["a.pdf", "b.pdf", "c.pdf"]: writer.append(pdf) # 追加整个文件 writer.append("d.pdf", pages=(0, 3)) # 只取 d.pdf 的第 0~2 页 writer.write("merged.pdf")

效果提示：append(file, pages=(start, stop))中 stop 不含，(0, 3)取前 3 页。处理页数极多的大文件时可能触发 Python 递归限制，可按 docs/user/merging-pdfs.md 的说明适当调大sys.setrecursionlimit。

pypdf 旋转页面与裁剪 mediabox

适合扫描件方向错误的文档，以及只保留页面局部区域的场景。

from pypdf import PdfReader, PdfWriter reader = PdfReader("example.pdf") writer = PdfWriter() writer.add_page(reader.pages[0].rotate(90)) # 顺时针旋转 90 度 page = writer.add_page(reader.pages[1]) page.mediabox.upper_right = (page.mediabox.right / 2, page.mediabox.top / 2) # 裁剪为左上半区 writer.write("out.pdf")

效果提示：旋转优先用page.rotate(90)，它会同步维护页面框坐标。坑点：裁剪只是调整视图框（viewbox），被裁掉的内容仍留在文件内部、可被恢复，并不等于真正删除内容。

进阶用法

给 PDF 加水印或印章

需求：给一批页面统一压上"草稿"水印或审批章，水印可以来自另一份单页 PDF。做法：读入印章页，对每页调用merge_page，over=False表示垫在底层做水印，over=True则盖在顶层做印章。

from pypdf import PdfReader, PdfWriter stamp = PdfReader("watermark.pdf").pages[0] writer = PdfWriter(clone_from="report.pdf") for page in writer.pages: page.merge_page(stamp, over=False) writer.write("report-watermarked.pdf")

收益：水印可先缩放旋转再合并（用merge_transformed_page配合Transformation），一份脚本即可批量处理整批文件，无需打开任何 GUI。下图为 pypdf 生成的水印叠加效果示例：

PDF 加密与解密

需求：对外发出的文档要加密码保护，收到的加密文件需要解开再处理。做法：加密时用writer.encrypt()指定密码和算法；解密前先判断reader.is_encrypted，再用reader.decrypt()输入密码。

from pypdf import PdfReader, PdfWriter writer = PdfWriter(clone_from="report.pdf") writer.encrypt("my-secret-password", algorithm="AES-256") writer.write("report-encrypted.pdf") reader = PdfReader("report-encrypted.pdf") if reader.is_encrypted: reader.decrypt("my-secret-password")

收益：AES-256 是目前推荐算法（文档同时提到AES-256-R5）；注意若不传algorithm参数，pypdf 出于兼容默认走 RC4，而 RC4 已被认为不安全，正式使用请显式指定 AES。

常见问题

问：pypdf 支持哪些 Python 版本，有没有操作系统限制？ 答：需要 Python 3.9 及以上（见 pyproject.toml 中requires-python = ">=3.9"），支持 3.9~3.14。库本身跨平台，无系统级限制；核心功能几乎只用标准库，仅 AES 加解密和图像提取需要额外依赖。

问：之前用的是 PyPDF2 或旧版 pypdf，升级要注意什么？ 答：pypdf 3.1.0 之后 API 有显著变化（如PdfWriter接管了原PdfMerger的大部分职责），从旧版本升级建议对照 docs/meta/migration-1-to-2.md 迁移文档逐项检查。

问：读取加密 PDF 报错或提示密码失败，怎么排查？ 答：先确认文件是否真的加密（检查reader.is_encrypted），再确认密码正确；若文件使用 AES 算法而你没有安装pypdf[crypto]，加解密会失败，安装对应依赖即可。提交 issue 时按仓库要求附上最小可复现示例（代码 + 出问题的 PDF +print(pypdf.__version__)的版本号）。

资源导航

• 官方文档（仓库内）：docs/，按用户指南、模块参考、开发说明分目录
• 项目说明：README.md
• 源码入口：pypdf/，核心读写逻辑在 pypdf/_reader.py 与 pypdf/_writer.py
• 版本记录：CHANGELOG.md

现在就试试：找一份手边的 PDF，运行上面的快速开始脚本，把首页文本打印出来，确认你的 pypdf 已经可用。

【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf