网站导航
> 技术文档 > 【Python】pypdf 库：处理 PDF 文件

【Python】pypdf 库：处理 PDF 文件

网友: 技术文档 2025-08-15 14:13:16

pypdf 是一个纯 Python 库，用于处理 PDF 文件。它支持读取、修改、合并、拆分、加密和提取 PDF 文件的文本、元数据及页面内容。pypdf 是 PyPDF2 的继任者（2022 年更名并重构），提供了更现代化的 API 和更高的性能，适合处理简单的 PDF 操作任务。

以下是对 pypdf 库的详细说明和常见用法。

1. pypdf 库的作用

  • 读取 PDF：提取文本、元数据、页面数量等。
  • 修改 PDF：合并、拆分、旋转、裁剪页面。
  • 创建 PDF：生成新 PDF 或添加内容（如文本、水印）。
  • 加密/解密：为 PDF 设置密码或解锁受保护的 PDF。
  • 跨平台：纯 Python 实现，无需外部依赖（如 Adobe Acrobat）。

2. 安装与环境要求

  • Python 版本：支持 Python 3.6+（推荐 3.8+）。
  • 依赖：无强制外部依赖，可选依赖：
    • Pillow：处理 PDF 中的图像。
    • pycryptodome：支持加密/解密。
  • 安装命令： 
    pip install pypdf
  • 可选扩展： 
    pip install pypdf[image] # 包含 Pillowpip install pypdf[crypto] # 包含 pycryptodome
  • 验证安装： 
    import pypdfprint(pypdf.__version__) # 示例输出: 5.0.1

3. 核心功能与用法

pypdf 的核心类包括 PdfReader（读取 PDF）、PdfWriter（修改/创建 PDF）和 PdfMerger（合并 PDF）。以下是主要功能和示例。

3.1 读取 PDF

使用 PdfReader 读取 PDF 文件，提取元数据、页面数和文本。

from pypdf import PdfReader# 打开 PDF 文件reader = PdfReader(\"example.pdf\")# 获取元数据metadata = reader.metadataprint(metadata) # 输出: {\'/Title\': \'Example PDF\', \'/Author\': \'John Doe\', ...}# 获取页面数print(len(reader.pages)) # 输出页面数# 提取第一页文本page = reader.pages[0]print(page.extract_text())

说明：

  • reader.metadata 返回 PDF 元数据（如标题、作者）。
  • reader.pages 是一个页面列表，pages[i] 返回第 i 页（从 0 开始）。
  • page.extract_text() 提取页面文本（效果依赖 PDF 结构，可能不完整）。
3.2 合并 PDF

使用 PdfMerger 或 PdfWriter 合并多个 PDF 文件。

from pypdf import PdfMerger# 创建合并器merger = PdfMerger()# 添加 PDF 文件merger.append(\"file1.pdf\")merger.append(\"file2.pdf\")# 保存合并结果merger.write(\"merged.pdf\")merger.close()

替代方法（使用 PdfWriter）：

from pypdf import PdfReader, PdfWriterwriter = PdfWriter()for pdf in [\"file1.pdf\", \"file2.pdf\"]: reader = PdfReader(pdf) for page in reader.pages: writer.add_page(page)with open(\"merged.pdf\", \"wb\") as f: writer.write(f)

说明：

  • PdfMerger 更适合简单合并任务。
  • PdfWriter 提供更灵活的控制。
3.3 拆分 PDF

将 PDF 拆分为单个页面或指定范围。

from pypdf import PdfReader, PdfWriterreader = PdfReader(\"example.pdf\")# 拆分每一页为单独 PDFfor i, page in enumerate(reader.pages): writer = PdfWriter() writer.add_page(page) with open(f\"page_{i+1}.pdf\", \"wb\") as f: writer.write(f)

说明：

  • 每个页面保存为单独文件。
  • 可通过索引选择特定页面范围。
3.4 旋转页面

旋转 PDF 的页面。

from pypdf import PdfReader, PdfWriterreader = PdfReader(\"example.pdf\")writer = PdfWriter()# 旋转第一页 90 度page = reader.pages[0]page.rotate(90)writer.add_page(page)# 保存结果with open(\"rotated.pdf\", \"wb\") as f: writer.write(f)

说明：

  • page.rotate(angle) 接受角度（顺时针，90 的倍数）。
  • 旋转后的页面添加到新 PDF。
3.5 加密/解密 PDF

为 PDF 设置密码或解锁受保护的 PDF。

from pypdf import PdfReader, PdfWriter# 加密 PDFreader = PdfReader(\"example.pdf\")writer = PdfWriter()for page in reader.pages: writer.add_page(page)writer.encrypt(user_password=\"my_password\", algorithm=\"AES-256\")with open(\"encrypted.pdf\", \"wb\") as f: writer.write(f)# 解密 PDFreader = PdfReader(\"encrypted.pdf\")if reader.is_encrypted: reader.decrypt(\"my_password\")print(reader.pages[0].extract_text())

说明：

  • encrypt 支持 RC4-128 和 AES-256 算法。
  • decrypt 需提供正确密码。
3.6 提取图像

从 PDF 中提取图像（需安装 Pillow）。

from pypdf import PdfReaderreader = PdfReader(\"example.pdf\")page = reader.pages[0]for img in page.images: with open(f\"image_{img.name}\", \"wb\") as f: f.write(img.data)

说明：

  • page.images 返回页面中的图像对象。
  • img.data 是图像的二进制数据。

4. 性能与特点

  • 高效性：纯 Python 实现，启动快，无需外部工具。
  • 内存效率：逐页处理，适合大型 PDF。
  • 灵活性：支持页面级操作和元数据修改。
  • 局限性：
    • 文本提取效果依赖 PDF 结构，复杂格式（如扫描文档）可能失败。
    • 不支持直接编辑 PDF 内容（如修改文本），需结合其他库（如 reportlab）。

5. 实际应用场景

  • 文档处理：合并报告、拆分章节、提取元数据。
  • 自动化工作流：批量处理 PDF（如添加水印、加密）。
  • 数据提取：从 PDF 提取文本或图像用于分析。
  • 电子书管理：调整页面顺序或裁剪边距。
  • 安全管理：为敏感文档设置密码。

示例（提取所有页面文本）：

from pypdf import PdfReaderreader = PdfReader(\"example.pdf\")text = \"\"for page in reader.pages: text += page.extract_text() or \"\"print(text[:200]) # 输出前 200 字符

6. 注意事项

  • 文本提取：
    • 扫描或图像型 PDF 需先用 OCR 工具（如 pytesseract）处理。
    • 复杂布局可能导致文本顺序错误。
  • 加密限制：
    • 某些高强度加密可能需要 pycryptodome。
    • 解密需正确密码，否则抛出异常。
  • 文件路径：
    • 确保文件路径正确，建议使用 pathlib 或绝对路径。
  • 版本兼容性：
    • pypdf（≥3.0.0）与 PyPDF2 不完全兼容，旧代码需调整。
    • 最新版本（5.0.1，截至 2025）优化了性能和 API。
  • 错误处理：
    • 处理 FileNotFoundError（文件不存在）。
    • 处理 PdfReadError（文件损坏或加密）。

7. 综合示例

以下是一个综合示例，展示读取、合并、加密和提取文本：

from pypdf import PdfReader, PdfWriter, PdfMerger# 读取 PDF 元数据和文本reader = PdfReader(\"input.pdf\")print(\"Metadata:\", reader.metadata)print(\"Page count:\", len(reader.pages))print(\"First page text:\", reader.pages[0].extract_text()[:100])# 合并多个 PDFmerger = PdfMerger()merger.append(\"input1.pdf\")merger.append(\"input2.pdf\")merger.write(\"merged.pdf\")merger.close()# 加密合并后的 PDFreader = PdfReader(\"merged.pdf\")writer = PdfWriter()for page in reader.pages: writer.add_page(page.rotate(90)) # 旋转页面writer.encrypt(user_password=\"secret\", algorithm=\"AES-256\")with open(\"encrypted_rotated.pdf\", \"wb\") as f: writer.write(f)

说明：

  • 读取元数据和文本。
  • 合并两个 PDF。
  • 旋转页面并加密输出。

8. 资源与文档

  • 官方文档：https://pypdf.readthedocs.io/
  • GitHub 仓库：https://github.com/py-pdf/pypdf
  • PyPI 页面：https://pypi.org/project/pypdf/
  • 教程：https://pypdf.readthedocs.io/en/stable/user/introduction.html
  • 迁移指南（从 PyPDF2）：https://pypdf.readthedocs.io/en/stable/user/migration.html
网络标签：

相关问题