很多人第一次用 Python 解析 PDF 时最先找到的往往是 PyPDF2 或 pypdf。但真正动手之后就会发现复制出来的文本断行严重表格变成一坨没有规律的字符更不要提“把某一列数据单独取出来”。PDF 在屏幕上看起来规规矩矩可在代码眼里它只是一堆“字符、直线、矩形”的绘制指令。如果你最近也在做 PDF 表格解析或者经常要把银行流水、合同清单、销售报表里的数据搬进 Excel那么 pdfplumber 值得你认真学一次。它最核心的价值不是多了一个读文本的 Python 库而是把 PDF 页面拆成了带坐标的结构化对象让你能定位每一个字符、每一条表格线然后按“业务字段”重新组织数据。今天是系列的第 42 天这一篇会用最小可运行的案例把 pdfplumber 读取 PDF 的完整链路讲清楚从环境安装、页面文本提取到表格解析最后写出一个“读取 PDF 表格并自动生成 Excel”的实战脚本。读完你会掌握的并不只是几个 API而是一套处理“PDF 数据搬运”类需求的通用思路。1. 解析 PDF 时真正难的不是读文字先问一个问题为什么 PDF 文件打开后那么稳定复制文字却那么痛苦原因在于PDF 本质上是为“印刷排版”设计的文件格式。它保存的是一张“画布”上每个字符在哪里、用什么字体、多大字号而不是像 Word 那样记录“这是一个段落”“这里有一个表格”。所以当你用普通文本工具去提取 PDF 时提取到的只是一堆字符的位置流而不是你看到的结构。举一个真实场景你拿到一份客户的月度对账单 PDF里面有一个 10 行 × 7 列的表格包括“交易日期、交易类型、收入、支出、余额”等字段。用 PyPDF2 提取文本后得到的更像这样2025-04-01 网银转账 12,300.00 4,200.00 86,900.00 2025-04-02 pos消费 0.00 356.00 86,544.00表格的“列”关系在这里消失了你很难判断 12,300.00 到底是收入还是支出。而 pdfplumber 的不同之处在于它会告诉你2025-04-01 这个字符串出现在页面的哪个坐标区域表格线在哪里单元格怎么切分。所以真正的需求并不是“读取 PDF 文本”而是“把 PDF 中某个区域里的字符按照业务需要重新还原成结构化数据”。如果只停留在学会一个extract_text()接口那远远不够。pdfplumber 真正值得学的地方是它把 PDF 解析拆成了几个不同的层面层面对应 pdfplumber 能力解决什么问题文档层pdfplumber.open()获取页数、元数据定位目标页面页面层page.extract_text()按浏览顺序把文字组合成字符串词/字符层page.extract_words()、page.chars获取每个词或字符的坐标、字体、大小表格层page.extract_table()、page.extract_tables()按表格线特征把单元格数据切成二维列表可视化层page.to_image()把页面渲染成图辅助确认布局和参数有了这层认识你的排查思路会很清晰文本取不到先看字符层有没有内容表格切不对先看页面有没有可用的线条遇到扫描件则要判断 PDF 是否根本没有文本层。2. 为什么选择 pdfplumber与 PyPDF2、Camelot 的对比在选择库之前先明确一点没有哪个库能处理所有类型的 PDF关键在于 pdfplumber 的适用边界在哪里。从日常办公自动化的角度看pdfplumber 的定位非常清晰。它主要处理“电子生成型 PDF”也就是由 Word、WPS、财务系统、ERP、电商后台等软件导出的 PDF。这类文件通常包含文本层字符信息可以被读取。而扫描件 PDF 本质是图片pdfplumber 不会做 OCR所以单靠它无法提取扫描图片中的文字。我把最常见的几个 Python PDF 方案放在一起比较方案文本提取表格提取坐标与调试适合场景PyPDF2 / pypdf中等复制时容易错位不直接提供需要自己拼弱合并、拆分、加解密、简单提取文字pdfplumber中等偏上可控制字符间距较好能识别有表格线的表格强需要保留文本坐标、表格结构化的办公场景Camelot一般表格提取能力强依赖较多中等大量、规则清晰的表格 PDF扫描件 OCR需要配合 OCR 引擎取决于识别结果由图像质量决定纸质扫描、无文本层的 PDF可以看出pdfplumber 的优势是“文本 坐标 表格”综合能力比较均衡。它底层基于 pdfminer.six 解析 PDF 内容流但提供了更友好的页面对象和视觉调试能力。如果你的需求是“从一份 PDF 中把某几列数据批量取出来再写进 Excel”pdfplumber 是更合适的起点。有人会问Camelot 是不是更专业Camelot 对表格效果确实不错但它依赖较多适合有大量表格且格式规律的生产项目。而 pdfplumber 胜在轻量、API 直观适合 100 天 Python 学习路线中快速落地。3. 环境准备安装 pdfplumber 与 openpyxl开始写代码前需要准备 Python 环境。这里假设读者已经安装过 Python 3.8 及以上版本。为了避免依赖混乱建议在项目目录下创建虚拟环境。Windows 下创建虚拟环境可执行python -m venv pdf_env pdf_env\Scripts\activatemacOS / Linux 下激活命令是source pdf_env/bin/activate激活环境后再安装依赖库pip install pdfplumber openpyxl如果网络较慢可以临时使用国内镜像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pdfplumber openpyxl这里安装两个库pdfplumber负责解析 PDF提取文本和表格。openpyxl负责把解析结果写入 Excel 的 .xlsx 文件。如果你更习惯用 pandas 做数据清洗也可以多装一个 pandas不过本文为了减少理解负担直接使用 openpyxl 操作单元格更透明。安装完成后可以用下面的命令检查版本pip show pdfplumber pip show openpyxl看到正常输出版本信息就说明安装成功。建议准备一个测试用 PDF。最快速的办法是在 Word 或 WPS 里插入一个 3 到 5 列的表格随便填几行数据然后另存为 PDF。这样你不会受外部文件格式影响也能比较清楚地观察 pdfplumber 的表格解析效果。有一点要提醒如果你把脚本命名为pdfplumber.py放在当前目录下运行时会因为“文件名遮蔽”导致 import 失败因为 Python 会优先把当前目录的同名文件当作模块。建议脚本命名为pdf_demo.py或extract_pdf_to_excel.py。4. pdfplumber 核心 API从打开文档到页面调试pdfplumber 的操作流程基本可以概括为五步打开文件、遍历页面、提取文字、提取表格、关闭资源。下面把每一步拆开看。先看最基础的打开 PDF 与遍历页面代码。# 文件路径01_quick_scan.py import pdfplumber pdf_path sample_table.pdf with pdfplumber.open(pdf_path) as pdf: print(总页数, len(pdf.pages)) print(PDF 元信息, pdf.metadata) first_page pdf.pages[0] print(第 1 页尺寸, first_page.width, x, first_page.height) print(第 1 页页号, first_page.page_number)这段代码做了四件事pdfplumber.open(pdf_path)打开文件返回一个 PDF 对象。pdf.pages是页面列表用len()可以拿到总页数。pdf.metadata是一些文档属性比如标题、作者、创建时间等具体字段取决于 PDF 是否写入。页面对象有width、height、page_number等常用属性。有人可能在代码结尾纠结要不要写pdf.close()。使用with pdfplumber.open(...) as pdf后文件会在代码块结束时自动关闭这是一种推荐写法。如果不用 with 语法就需要记得手动关闭。接下来看文本提取。把下面这段代码保存为02_extract_text.py# 文件路径02_extract_text.py import pdfplumber pdf_path sample_table.pdf with pdfplumber.open(pdf_path) as pdf: for page in pdf.pages: text page.extract_text() print( Page, page.page_number, ) print(text)extract_text()返回的是字符串。它并不是简单的“把所有字符拼起来”而是会利用每个字符的坐标来推断换行顺序。对于大多数常规 PDF这个结果已经能保持相对正常的阅读顺序。但需要注意一点对于复杂的双栏排版 PDFextract_text()的阅读顺序可能会错。比如先读完了右栏再读左栏或者把两栏混在一起。如果遇到这种情况通常要继续用 extract_words 按坐标自定义排序但办公场景下的单栏单据比较多见所以这里先掌握基础。如果你想进一步查看页面里每个词的坐标可以试试# 文件路径03_extract_words.py import pdfplumber pdf_path sample_table.pdf with pdfplumber.open(pdf_path) as pdf: page pdf.pages[0] words page.extract_words() for word in words[:5]: print(word)每一条 word 结果类似一个字典包含text、x0、top、x1、bottom、upright等字段。x0 和 top 代表这个词左上角的坐标x1 和 bottom 代表右下角坐标。这在后续按区域提取数据时非常有用例如只提取表格中间某一列的文字而不是全页所有文字。关于页面调试还有一个常用方法# 文件路径04_debug_page.py import pdfplumber pdf_path sample_table.pdf with pdfplumber.open(pdf_path) as pdf: page pdf.pages[0] try: # 把页面渲染成图片方便观察表格线和文字位置 page.to_image(resolution150).save(page_preview.png) print(预览图已保存page_preview.png) except Exception as e: print(页面渲染失败但不影响后续文本/表格提取, e)page.to_image()适合在调表格参数时使用。通过预览图你能直观看到 PDF 页面的表格线、文字间距进而判断为什么某一种表格策略不生效。如果环境中缺少渲染后端出现异常时不要慌这只是辅助调试功能不是提取文本和表格的必需能力。5. 表格提取原理为什么表格会切错列表格是 PDF 处理中最容易“翻车”的部分。理解 pdfplumber 提取表格的基本原理能帮你少走很多弯路。PDF 页面中没有“单元格”这种高级对象。它只有两种基础元素文字和线条。表格在 PDF 内部其实就是一堆字符加上一堆横线竖线。pdfplumber 做表格识别时会把页面横线竖线的位置找出来再根据文字所处的坐标区域把字符划分进不同格子最终生成“二维列表”。extract_tables()返回的结果是一个列表的列表最外层代表页面中的多张表格每一张表格又由行组成每一行由单元格内容组成。例如[ [ [产品, 数量, 单价], [A, 10, 99.00], [B, 20, 199.00] ] ]pdfplumber 的表格识别使用table_settings参数来控制。最常见的两个参数是vertical_strategy决定竖线边界怎么找。horizontal_strategy决定横线边界怎么找。默认情况下pdfplumber 会尝试通过“线条”来分割表格。当 PDF 表格没有完整线条或者线条被底纹、字体遮挡时就可能导致提取结果为空或列错乱。此时可以考虑把vertical_strategy改为text让代码尝试“根据文字左右分布”来推断列边界。下面是一个包含备选策略的表格提取函数# 文件路径05_extract_tables.py import pdfplumber pdf_path sample_table.pdf def get_tables(page): 优先使用默认 lines 策略如果没提取到再尝试 text 策略。 tables page.extract_tables() if tables: return tables table_settings { vertical_strategy: text, horizontal_strategy: text, min_words_vertical: 2, min_words_horizontal: 1, } return page.extract_tables(table_settingstable_settings) with pdfplumber.open(pdf_path) as pdf: for page in pdf.pages: tables get_tables(page) print(页面, page.page_number, 提取到, len(tables), 张表格) for table_index, table in enumerate(tables, start1): print(表格编号, table_index) for row in table: print(row)这里顺带把min_words_vertical和min_words_horizontal展示出来它们影响 text 策略下的分割灵敏度。如果看不懂可以先把它们当成两个调节旋钮实际遇到“列被切多”“行被切多”的问题时再回头调整就行。在真实的 PDF 里表格解析失败最常见的原因并不是代码语法问题而是“这个表格在 PDF 里长得并不像一个规整表格”。例如只有横线没有竖线。单元格背景有填充色把部分线条盖住。表格单元格里的文字跨行。表格中嵌入了图片。遇到这些情况第一反应不应该是增加复杂的自动识别算法而是先用视觉预览确认页面结构再针对这一类型的页面写固定规则。6. 完整实战批量提取 PDF 表格并写入 Excel这一节进入核心内容把 PDF 中的表格提取出来并写入一个 Excel 工作簿。整体设计思路是遍历 PDF 的每一页。提取每一页的文本做预览日志。提取每一页的表格。每页生成一个独立的 Excel Sheet避免数据互相干扰。最后保存为 .xlsx 文件。代码会稍微多一点但结构并不复杂。建议先全文阅读再复制到本地运行。# 文件路径pdf_to_excel.py # 功能读取 PDF 页面中的表格按页写入 Excel import pdfplumber from openpyxl import Workbook def get_tables(page): 提取页面中的表格。 优先按默认线条策略提取若失败改用 text 策略。 这是应对常见 PDF 表格比较实用的兜底方式。 tables page.extract_tables() if tables: return tables table_settings { vertical_strategy: text, horizontal_strategy: text, min_words_vertical: 2, min_words_horizontal: 1, } return page.extract_tables(table_settingstable_settings) def pdf_tables_to_excel(pdf_path, xlsx_path): 把 pdf_path 中每页的表格写入 xlsx_path wb Workbook() # 删除默认自动生成的空 Sheet后续统一按页创建 wb.remove(wb.active) with pdfplumber.open(pdf_path) as pdf: print(PDF 总页数, len(pdf.pages)) for page_no, page in enumerate(pdf.pages, start1): print(处理第, page_no, 页...) # 页面文本预览方便排查该页内容 text page.extract_text() or print(----- 该页文本前 300 字 -----) print(text[:300]) print(----------------------------) # 每页创建独立 Sheet名称不能重复且不能超过 31 字符 ws wb.create_sheet(titlefPage{page_no}) # row_cursor 表示当前写入 Excel 的行号 row_cursor 1 tables get_tables(page) print(该页提取到表格数量, len(tables)) if not tables: ws.cell(row_cursor, 1, f第{page_no}页未提取到表格) row_cursor 1 continue for table_index, table in enumerate(tables, start1): # 每个表格前写一行来源标记便于核对 ws.cell(row_cursor, 1, fPage {page_no} - Table {table_index}) row_cursor 1 for row in table: for col_index, value in enumerate(row, start1): # pdfplumber 对空单元格返回 None统一转成空字符串 if value is None: value cell ws.cell(rowrow_cursor, columncol_index) cell.value str(value) row_cursor 1 # 每张表格结束后留一个空行避免多张表黏在一起 row_cursor 1 wb.save(xlsx_path) print(Excel 已生成, xlsx_path) if __name__ __main__: pdf_tables_to_excel(sample_table.pdf, output_tables.xlsx)这段代码的核心逻辑并不复杂关键点有三个。第一with pdfplumber.open(pdf_path) as pdf负责自动关闭资源比手动 close 更省事。第二get_tables(page)加了一个兜底策略。大多数由 Word 生成的表格 PDF默认策略可以解析成功没有表格线的扫描样式表格往往需要 text 策略来兜底。但这并不意味着一定能拿到完美结果它只能提高成功率。第三Excel 的 Sheet 名称不能重复。这里使用 fPage{page_no}只要有页码就是唯一的同时长度也不会超过 Excel 限制。如果希望把文本内容也保存到 Excel 中以便后续人工核对可以在get_tables(page)之外再做一个 sheet把page.extract_text()的全文写进去。业务上一个比较常见的做法是为每个 PDF 文件生成两个 Sheet一个叫数据表一个叫文本备份。这样即使表格解析出错文本备份也能帮你定位数据和对应页面。补充一个基于 pandas 的极简写法。如果你已经习惯用 pandas表格数据转 Excel 会更短# 文件路径pdf_to_excel_pandas.py import pdfplumber import pandas as pd pdf_path sample_table.pdf xlsx_path output_pandas.xlsx with pdfplumber.open(pdf_path) as pdf: with pd.ExcelWriter(xlsx_path, engineopenpyxl) as writer: for page_no, page in enumerate(pdf.pages, start1): table page.extract_table() if not table: continue # 第一行数据作为表头 df pd.DataFrame(table[1:], columnstable[0]) df.to_excel(writer, sheet_namefPage{page_no}, indexFalse)如果 PDF 页面里有多张表格extract_tables()返回多个表这时需要逐个编号后写入不同 Sheet或者在同一 Sheet 里用空行分隔。pandas 写法更适合单页单表结构多表场景建议使用 openpyxl 版本控制粒度更高。7. 运行结果与效果验证在命令行中执行核心脚本python pdf_to_excel.py如果你的测试文件名称不是sample_table.pdf记得先修改脚本最后的文件名参数。正常运行时控制台可能会出现类似下面的输出PDF 总页数 1 处理第 1 页... ----- 该页文本前 300 字 ----- 产品表 产品名称 数量 单价 备注 A 10 99.0 测试 B 20 199.0 测试 ---------------------------- 该页提取到表格数量 2 Excel 已生成 output_tables.xlsx注意不同 PDF 的文本预览结果不同上面的输出只是用来示意。关键验证点是控制台能打印“PDF 总页数”说明文件打开成功。能看到表格数量大于 0说明extract_tables()有实际返回。项目目录下生成output_tables.xlsx双击打开后表格数据按行排列。如果某页没有提取到表格代码会在 Excel 对应 Sheet 里写一行“第 X 页未提取到表格”。这是程序在告诉你该页的结构可能需要调整参数而不是程序崩溃了。打开生成的 Excel 时可以重点检查三处Sheet 名称是否为 Page1、Page2 等。表格列顺序是否和 PDF 预览一致。数量、金额字段是否出现串列现象例如本应属于“单价”的 99.0 出现在了“数量”列。如果出现串列多半是 PDF 表格的列边界切分不准确。建议先把某一页的extract_tables()结果打印到控制台观察每一行的列表长度和值分布再针对性地调table_settings。还要提醒一点Excel 中的数据默认都是字符串因为pdfplumber提取出来的单元格内容本身是字符串。如果你需要对金额求和在写入 Excel 时需要用 Python 把字符串转换成float否则 Excel 里只是文本。对于大量报表场景更推荐在写入前用 Python 完成清洗而不是事后一个个点在 Excel 里改格式。8. 常见问题与排查思路pdfplumber 使用中最常遇到的现象并不是报错而是“不报错但结果不对”。这类问题排查起来更费时间下面把典型情况整理成一张排查表。问题现象可能原因排查方式解决方案代码运行报pdfplumber找不到没有安装库或脚本名与库名冲突执行pip show pdfplumber检查当前目录是否有 pdfplumber.py安装依赖将脚本改名extract_text()返回空字符串扫描件 PDF 没有文本层或字体编码无法映射用 PDF 阅读器搜索文字用page.chars判断字符是否存在无文本层时考虑 OCR字符存在但乱码则处理字体映射表格提取出来的列对不上表格线不完整或列边界识别错误打印page.extract_tables()原始结果用page.to_image()看页面调整table_settings尝试vertical_strategytext表格中某列文字丢失单元格文字过密被文字策略错误合并打印page.extract_words()观察文字坐标修改x_tolerance、y_tolerance参数重新提取生成的 xlsx 打不开提示损坏文件被其他进程占用或磁盘写入中断检查 Excel 文件是否已打开查看保存路径权限关闭已打开文件换个输出文件名重试页面渲染图片失败缺少 PDF 渲染后端查看报错提示不影响表格提取可以跳过调试图片中文变成乱码或空心方块PDF 字体没有正确的 Unicode 映射观察 PDF 是否能正常复制如果 PDF 本身无法复制中文只能靠 OCR如果只是 Excel 显示问题则检查字体同一个 PDF 某些页有表格另一些没有不同页面的表格结构差异较大逐页打印文本单独查看失败页对不同页面使用独立的table_settings不要全局套用一个规则这里补充说明一点很多刚接触 PDF 解析的人会以为“中文乱码”是 pdfplumber 不支持中文。实际上 pdfplumber 支持中文文本提取关键在于 PDF 内部字体有没有保存正确的字符映射。如果一段中文在 PDF 阅读器中能复制出来通常 pdfplumber 也能提取如果 PDF 本身是扫描图片那就不是 text 层能解决的问题需要 OCR 介入。排查问题的推荐顺序是先用阅读器人工确认 PDF 有没有文本层。再用page.extract_words()确认字符是否存在。接着用page.extract_text()看整页文本是否正常。最后才用page.extract_tables()判断表格结构是否解析正确。按照这个顺序你会很快定位问题是出在“字符层丢失”“文本顺序错误”还是“表格切分规则不合适”。9. pdfplumber 的最佳实践与工程建议学会 API 只是第一步真正把 PDF 处理做好还需要一些工程层面的经验。9.1 先看页面再定参数不要一上来就写一套“通用表格解析函数”。PDF 的世界里几乎不存在完全通用的规则。拿到一个陌生 PDF第一件事应该是随机抽几页用阅读器或 pdfplumber 把页面转成图片观察表格长什么样。确认版面后再决定使用 lines 策略还是 text 策略。9.2 以“批处理”视角设计代码办公场景下很少只处理一份 PDF。更常见的情况是某个文件夹下有几百份格式相同的 PDF例如按月份导出的财务报表。这时建议先写一个“单文件解析函数”再用pathlib.Path.glob()遍历文件夹。要注意的是批处理前务必验证样本文件解析结果。如果样本文件是 A4 纵向而另一些文件是横向同样的参数很可能失效。所以遍历时要把文件名、页数、提取到的表格数量写入日志方便事后抽查。9.3 数据清洗要与解析分离pdfplumber 提取出的单元格内容经常带有前后空格、无关换行、货币符号。如果把这些清洗逻辑堆在解析函数里代码很快会变得难以维护。建议设计成三个阶段提取阶段只负责把 PDF 表格转成二维列表。清洗阶段处理空格、空值、类型转换。输出阶段写入 Excel 或数据库。三阶段分离后你可以单独对清洗逻辑写测试也方便后续要导入数据库时复用。9.4 表格解析后必须做数据校验PDF 解析不是“百分百准确”的操作。将数据写入 Excel 之前建议做几个基础维度的校验行数是否与 PDF 预览一致。关键数值列是否有非数字内容。表头是否包含预期字段名。例如你解析对账单时发现“金额”列全是None说明程序很可能把列切错了。提前校验能节省大量核对时间。一个简单的校验思路是把 PDF 文本层中提取到的总行数与表格解析结果的总行数作对比如果数字差距很大大概率是表格识别策略有问题。9.5 敏感文件注意合规在实际开发中PDF 经常包含合同、客户资料、财务明细和内部报表。处理前应当确认自己有权处理该文件并遵守公司和项目的数据安全要求。测试代码时尽量使用脱敏的样例数据不要把客户真实信息直接打到日志里。如果要把解析结果发给其他同事最好只保留业务字段不要连坐标信息、内部文件名一起保留。9.6 依赖版本尽量固定pdfplumber 的 API 在不同版本之间变化不大但为避免意外差异生产项目建议把依赖版本写入requirements.txt。可以用pip freeze requirements.txt生成当前环境的依赖列表也可以手动指定主版本号。如果你今天跟着教程学习只用最新版本即可。一个简单的 requirements 示例pdfplumber0.11.0 openpyxl3.1.2版本号请以你实际安装到的为准不用刻意锁到某个版本。这里举例是为了说明固定依赖的方式。10. 总结与下一步建议这篇内容把 pdfplumber 处理 PDF 的完整链路梳理了一遍。你已经接触到了PDF 难解析的本质原因即它保存的是排版绘制信息不是业务数据结构。pdfplumber 与 PyPDF2、Camelot 的分工差异。PDF 打开、页面遍历、文本提取、词对象查看、表格提取的常用接口。一个可以落地的“PDF 表格批量导入 Excel”脚本。常见表格解析问题和排查顺序。接下来的实践路径建议按三步走。第一步用自己生成的表格 PDF 跑通上面的脚本观察文本、表格的原生输出结果。这是建立直觉的关键。第二步准备一份真实业务中经常遇到的 PDF可能是银行流水、采购明细或客户开票记录尝试用 pdfplumber 提取其中一页。过程中肯定会遇到列错位、表格拆分行等问题这正是理解table_settings的最好时机。第三步如果 PDF 解析稳定性要求高可以继续学习两点一是把 excel 结果改成数据库写入用 Python 的sqlite3或SQLAlchemy保存二是针对“扫描件 PDF 无法提取文本”的情况学习 OCR 工具链例如pytesseract配合图像预处理。说到底pdfplumber 只是帮你从 PDF 中“拿到字符和线条”。真正有价值的是你清楚自己的业务目标要知道哪些字段必须保留哪些表格区域需要忽略以及如何验证最终结果没有丢失数据。掌握这套思路后再遇到“老板丢来 50 份 PDF 让你整理成 Excel”的任务你就不会想手动复制粘贴了。
