Python PDF 转 Markdown：从单文件到批量处理

如何选择 Python PDF 转 Markdown 方案

选择方案时要看你会处理什么版式和输入格式。若主要处理 PDF，可先评估 PyMuPDF4LLM：它能返回 Markdown、JSON 或纯文本，并提供版面分析、分页分块、OCR 和图片导出选项。如果输入还包括 Word、PowerPoint、Excel 等文件，可以比较 Microsoft 的 MarkItDown 项目。其维护者说明，该项目面向 LLM 和文本分析，输出不一定适合要求高保真的人工阅读场景。偶尔转换单个文件时，浏览器工具更省配置；后端应用需要任务化处理时，可评估托管 API，但要考虑文件传输和服务控制。先用有代表性的文档对比结果，再确定方案。

用 Python 将单个 PDF 转成 Markdown

PyMuPDF4LLM 提供直接的 to_markdown() 调用，返回 Markdown 文本，因此脚本可以自行决定保存路径和文件名。先在实际运行脚本的环境安装该库，再选一份有代表性的 PDF 试跑，不要一开始就对整个资料库批处理。下面的基础示例使用项目文档中的包名和方法。

import pymupdf4llm
from pathlib import Path

source = Path("report.pdf")
markdown = pymupdf4llm.to_markdown(str(source))
output = source.with_suffix(".md")
output.write_text(markdown, encoding="utf-8")

print("已保存：", output)

安装解析库并写入 Markdown 文件

如果脚本属于某个项目，建议在独立虚拟环境中安装依赖，避免 PDF 解析依赖意外影响其他 Python 工作。官方文档列出的安装命令是 pip install pymupdf4llm。示例将 .md 文件保存到源 PDF 同一目录，并显式指定 UTF-8，避免依赖系统默认文本编码。若应用会接收用户文件，解析前应校验扩展名和大小，明确选择输出目录，也不要误把生成文件写进网站公开目录。

第一次运行应保持简单：转换一份 PDF，用纯文本编辑器打开 .md，再对照原文件检查。这样可以先确认默认解析效果，再决定是否把脚本扩展成批处理。长期运行的流程可能依赖可选参数；在锁定参数前，应查看当前官方 API 文档，因为包的能力会随版本变化。

扫描版 PDF 要先考虑 OCR

PyMuPDF4LLM 会检查页面，并在判断需要识别时自动使用 OCR。2026-10-02 核对的官方文档列出了 Tesseract 和 RapidOCR 适配器。请确保运行 Python 的同一环境中有可用 OCR 引擎；使用 Tesseract 时，还要安装文档语言对应的数据包。如果扫描件导出的文字很少，先检查已安装的库版本、OCR 引擎和语言数据。只有原生文本层损坏或自动检测漏掉页面时，才考虑设置 force_ocr=True：它会跳过常规检测并强制识别，因此可能拖慢本来清晰的数字文本页，也可能降低输出质量。请对照扫描件复核姓名、编号、金额和混合语言文本。

import pymupdf4llm

# OCR runs automatically when the installed engine detects that a page needs it.
markdown = pymupdf4llm.to_markdown("scanned-report.pdf")

# With Tesseract, choose language data installed in the environment.
markdown = pymupdf4llm.to_markdown(
    "scanned-report.pdf",
    ocr_language="eng+chi_sim",
)

用可预测的路径批量处理 PDF

批量转换首先是文件管理问题。源文件和输出文件应分开放，循环前先创建目标文件夹，并用每个 PDF 的文件名生成 Markdown 文件。按单个文件捕获异常，可以避免某份损坏或受密码保护的 PDF 让整个文件夹的任务无声中断。失败记录应写入操作人员能检查的日志；不要在任务失败后仍显示全部完成。大规模处理时，应先测量内存使用和解析库行为，再考虑有上限的并发。

下面代码处理一个目录的第一层文件。如果需要扫描子目录，可以换成 rglob("*.pdf")；同时保留相对路径，避免不同目录下同名的 report.pdf 相互覆盖。若这是持续运行的服务端任务，而不是本地脚本，可以把这种方式与带任务状态的 API 比较，评估鉴权、重试和文件保留方式。

from pathlib import Path
import logging
import pymupdf4llm

source_dir = Path("pdfs")
output_dir = Path("markdown")
output_dir.mkdir(parents=True, exist_ok=True)
logging.basicConfig(
    filename=output_dir / "conversion.log",
    level=logging.ERROR,
    format="%(asctime)s %(levelname)s %(message)s",
)

for pdf_path in sorted(source_dir.glob("*.pdf")):
    try:
        markdown = pymupdf4llm.to_markdown(str(pdf_path))
        target = output_dir / (pdf_path.stem + ".md")
        target.write_text(markdown, encoding="utf-8")
    except Exception:
        logging.exception("Could not convert %s", pdf_path.name)

让图片和表格在 Markdown 中保持可用

普通 Markdown 可以表达标题、列表、链接和不少简单表格。复杂表格、图表、公式和页面插图可能需要另一种表达方式，或单独保存图像资源。如果输出依赖 PDF 中提取的图片，应查看当前版本关于 write_images、图片路径和格式的参数说明；将资源文件与 Markdown 放在可预期的位置，并检查 .md 中生成的引用在实际阅读环境里能正常访问。不要假设每张图都能自动变成准确的文字说明，也不要以为原始页面排版会原样保留。

用于知识库时，可保留足够上下文，让读者能回到源 PDF 的对应页面核对重要段落。是否输出分页文本或元数据，要根据检索器和引用方式选择。如果更关注浏览器导出图片和表格后的整理，可参考PDF 转 Markdown 图片与表格指南。本站已有 PDF 转 Markdown 的 RAG 指南讨论切块和检索准备；本文集中在 Python 提取环节。

markdown = pymupdf4llm.to_markdown(
    "report.pdf",
    write_images=True,
    image_path="output_assets",
    image_format="png",
)

排查 Python PDF 转 Markdown 的常见问题

如果 Python 无法导入解析库，先确认运行脚本的解释器。请在同一个虚拟环境中执行 python -m pip show pymupdf4llm；Notebook、终端和定时任务有时会使用不同的 Python。遇到 FileNotFoundError，常见原因是相对路径按意外的工作目录解析。调试时打印 source.resolve()，或先用绝对路径验证。

扫描版 PDF 几乎没有文本时，应确认运行环境里有 OCR 引擎和对应语言数据。只有原生文本层缺失或不可信时才使用 force_ocr=True；清晰的数字 PDF 通常不必强制 OCR。若 Markdown 引用了不存在的图片，请将导出的资源目录与 .md 文件放在一起，并检查实际相对路径。

批处理应为每个输入记录成功或失败，并把异常细节写入日志。生成了 Markdown 文件只代表解析器返回了内容，并不能证明每一页、表格或识别出的数值都正确。

依赖输出前先检查 Markdown

函数成功返回，只表示解析器生成了内容，并不代表它正确还原了文档结构。在索引、发布或抽取业务事实前，应挑选几页对照源 PDF，至少包括开头页、分栏页、表格页、脚注或重复页眉页，以及资料中存在的扫描页。若输出不符合需求，就调整参数，或把难处理的文件路由给其他方案。

了解 PDF 转 Markdown 无法保证什么

PDF 记录的是页面如何绘制内容，并不总是包含 Markdown 所需的语义结构。双栏论文、表单、工程图和普通文本报告对应不同的解析问题。具备版面分析能力的软件可以作出有用推断，但仍应根据原页和后续用途判断结果。如果表格、公式或图示必须准确，应保留原始 PDF，并在 Markdown 旁边记录页码或保存独立资源。

本地处理可以让文件留在你控制的环境内，但安全性还取决于依赖、存储路径、日志、备份和进程隔离。Microsoft MarkItDown 文档提示，转换过程会使用当前进程已有的访问权限；处理不可信文档时，应隔离任务并限制文件访问。PyMuPDF4LLM 仓库声明 AGPL-3.0；若要分发使用它的产品，请先核对当前许可和依赖条款。托管 API 可以减少维护解析服务的工作，但仍需审阅上传与保留规则。若要搭建托管流程，可查看 PDF 转 Markdown API 指南；若只想快速预览有文本层的文件，可返回在线 PDF 转 Markdown 转换器。

Python PDF 转 Markdown 常见问题

一个稳妥的起步流程

本地脚本可以先安装文档说明的解析库，转换一份文件，将结果按 UTF-8 保存并与原文对照。仅在资料确实需要时，再加入 OCR、批处理和图片提取。保留失败日志，并在用于检索或决策前检查输出。如果不需要可重复的 Python 流程，可使用浏览器版 PDF 转 Markdown 工具；如果要托管任务，可查看PDF 转换 API 指南。