3 分钟跑通 pypdf：免费纯 Python 的 PDF 合并、拆分、水印与文本提取指南

3 分钟跑通 pypdf：免费纯 Python 的 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

你有多少次为"合并几个 PDF"这件事卡住过？用鼠标在软件里一页页拖，拖错顺序重来；或者把公司文件传到在线工具上，心里发毛，万一传出去呢？再或者花几百块买一套 PDF 套件，结果 90% 的功能你只用了"合并"这一个按钮。

今天要介绍的主角是pypdf：一个纯 Python 写的开源 PDF 库，合并、拆分、裁剪、旋转、加水印、提取文本、加密解密，全部能在几行代码里搞定。它不需要图形界面、不上传任何文件，还能直接写进你的脚本和自动化任务里。安装上只有一条pip install pypdf，核心功能零第三方依赖，几乎不会遇到依赖冲突。

上图为 pypdf 为文档逐页叠加半透明水印的实际效果——这正是后文要带你用十几行代码复现出来的成果。

它凭什么替代老办法

先说清楚你换工具能省下什么。pypdf 是 BSD-3-Clause 许可的开源项目，完全免费、纯 Python、本地运行：

维度	pypdf	付费 PDF 软件	在线转换工具
成本	免费开源	订阅制，年年掏钱	免费但有文件大小限制
隐私	全程本地处理，文件不出电脑	本地处理	文件要上传到别人服务器
自动化	可写脚本，批量上百个文件	手动点鼠标	单文件逐个上传
可定制性	完全可编程，任意改造	有限预设选项	无定制能力
依赖	纯 Python，轻量	大型软件	依赖网络

一句话：以前花钱、手点、上传的事，现在免费、自动、本地搞定。

一条命令跑通最小闭环

你此刻最大的顾虑大概是"装不上"或"版本不兼容"。先花 10 秒确认 Python 版本（pypdf 要求 Python 3.9 或更高）：

python --version

然后一条命令装好，就这么简单：

pip install pypdf

装完立刻验证一下，跑通最小闭环——打印版本号、读一下 PDF 页数。这里拿仓库自带的样例 PDF 测试，不用自己找文件：

import pypdf print(pypdf.__version__) # 打印你刚装好的版本号 reader = pypdf.PdfReader("sample-files/09-simple-annotations/annotated.pdf") print(len(reader.pages)) # 打印页数

看到版本号和一个大于 0 的页数，恭喜，已经跑通了！环境、依赖、Python 版本全部没问题，后面所有任务都建立在它上面。

真实任务走一遍：给合同批量加保密水印

假设你要给一份多页合同的每一页都盖上"CONFIDENTIAL"水印。老办法是打开软件逐页插入图片；用 pypdf，核心就是merge_page一个方法——它把水印叠印到页面上（不是把两页接起来），水印默认在文字底下，不影响阅读。

from pypdf import PdfReader, PdfWriter reader = PdfReader("合同.pdf") watermark = PdfReader("水印模板.pdf").pages[0] # 水印模板只需取第一页 writer = PdfWriter() for page in reader.pages: page.merge_page(watermark) # 把水印叠到当前页 writer.add_page(page) with open("合同-水印版.pdf", "wb") as f: writer.write(f)

运行完你会得到一份新 PDF：每一页都盖着半透明水印，原文字清晰可读。想调整水印的位置、大小、旋转角度，看 docs/user/add-watermark.md 就行，那里还有用Transformation控制缩放位移的完整示例。

按需选装依赖：解锁哪些能力

pypdf 的设计哲学是"核心零依赖、高级能力按需装"。你不需要一次全装，对照下面的能力清单挑就行（完整列表见 docs/user/installation.md）：

安装命令	解锁能力	什么时候用
pip install pypdf[image]	图像提取（装 Pillow）	要从 PDF 里抠出图片
pip install pypdf[crypto]	AES 加密解密（装 cryptography）	给 PDF 设密码、读加密 PDF；只用到 RC4 时核心包就够
pip install pypdf[fonts]	字体工具（装 fonttools）	需要精细处理字体
pip install pypdf[rtl_text]	阿拉伯语等右起文字排版	处理 RTL 语言文档
pip install pypdf[full]	上面全部一次装齐	不确定要什么时的一站式方案

生产环境建议只装实际用到的那一项，项目体积和潜在攻击面都更小。

上生产前必看

三个最容易踩的坑，一次说清。

1. 文件不合规怎么办。PDF 规范有一千多页，现实中的文件经常"不守规矩"。PdfReader有个strict参数：strict=True（默认）遇到不规范直接抛异常，strict=False则尽力抢救并打警告。调试时建议用严格模式暴露问题，上线时可按需放宽。详见 docs/user/robustness.md。

2. 错误要精准捕获。pypdf 的错误类是一套有层级的家族，别一律抓Exception：

try: reader = PdfReader("待处理.pdf") except pypdf.errors.PdfReadError as e: print(f"读取失败: {e}") # 空文件、密码错误、流损坏都会落到这里

WrongPasswordError、EmptyFileError这些都是它的子类，需要分别处理时按家族往下抓即可。

3. 版本与升级。pypdf 4.x 起每个版本都兼容所有受支持的 Python（3.9 到 3.14，见pyproject.toml），保持向后兼容。建议：新项目直接用最新版，老项目定期pip install --upgrade pypdf，既能拿到性能改进也能及时打上安全修复。

收尾与行动清单

回顾一下你刚走过的路：一条命令装好 pypdf，一次验证跑通环境，十几行代码给合同批量盖完水印——全程免费、本地、可重复。

接下来你可以马上做的几件事：

1. 把今天的水印脚本改成循环，处理整个文件夹的 PDF
2. 从一份长 PDF 里提取文本，走一遍 docs/user/extract-text.md
3. 试一次writer.append()把几个 PDF 合并成一个
4. 需要密码保护时，装pypdf[crypto]并参考 docs/user/encryption-decryption.md
5. 遇到怪文件，先查 docs/user/robustness.md，再用pypdf.__version__记录版本信息去提问

告别逐页拖拽，拥抱 Python 自动化——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