markitdown 离线格式转换：一条命令把 PDF、Word、Excel 变结构 Markdown

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown

markitdown 是把 PDF、Word、Excel、EPUB、图片、音频转成 Markdown 的离线工具。读完本文你能装好跑通、写出批量转换循环、给扫描件选对 OCR 路线。

先判断：拿来做什么 / 别拿它做什么

• 适合：文档进大模型问答、建知识库——输出是结构化 Markdown，token 省，全程本地离线。
• 前提：Python 3.10–3.14，装之前先确认环境。
• 避开：像素级排版还原。输出是给文本分析消费的，不是拿去做二次出版的。
• 注意：扫描版 PDF。内置转换器只读文字层，纯图片的扫描件会转出空内容，需要 OCR 插件或云端端点。
• 注意：格式按需装配。对应可选依赖没装时该格式直接不可用，报的是转换失败，别当成文件坏了。

2 分钟跑通：从安装到第一条命令

第 1 步，安装。一条命令装齐所有格式支持：

pip install "markitdown[all]"

装完得到markitdown命令行工具和 Python 包。只要几种格式就按需装，比如pip install "markitdown[pdf,docx]"只覆盖 PDF 和 Word。

第 2 步，跑第一条命令。

markitdown book.epub -o book.md

它按格式选转换器，把结果写进book.md；不加-o时结果直接打印到终端，适合快速预览。手头没有 EPUB 的话，先 clone 仓库（https://gitcode.com/GitHub_Trending/ma/markitdown），把文件名换成自带的测试素材 packages/markitdown/tests/test_files/test.epub 即可。

跑通后你会看到：book.md开头是Title:、Author:这类加粗元数据字段（从 EPUB 的 content.opf 自动带出），正文的标题、列表、表格全部变成对应的 Markdown 结构——看到这些就算成。

场景实操：markitdown 转 Markdown 能做什么

文档进大模型问答

大模型原生认 Markdown，token 消耗也低，"文档转 Markdown"是喂料的标准动作。带文字层的数字 PDF、Word 合同、HTML 网页、CSV/JSON 文本类格式都能转，管道输入也支持：

cat example.pdf | markitdown

它从标准输入读字节流并自动嗅探格式，-x、-m、-c参数可以手动提示扩展名、MIME 类型和编码，输出结构化文本。下面是项目测试素材里的一页学术论文，转完后标题、作者行、正文段落都会变成结构化文本：

批量转换表格和幻灯片进文本库

Excel 自动变 Markdown 表格，PPT 按幻灯片切分，Word 保留标题层级，文档里的公式转成 LaTeX。命令不变，换文件名即可：

markitdown report.docx -o report.md

会议纪要、财务报表批量进文本库后，可以直接全文检索，不用打开 Office 软件。

图片元数据与音频转录

图片会提取 EXIF 元数据（设备、拍摄时间、坐标）输出成 Markdown 字段；wav、mp3 能转录成文字（需[audio-transcription]依赖）；YouTube 链接直接传，先抓字幕再转换（需[youtube-transcription]依赖）。

上面这种仓库里的测试图，传入 LLM 客户端后，markitdown 还能顺带生成一句图片描述。

进阶：markitdown API、批量转换与插件

Python API。写自动化流程时用代码调，核心就三行：

from markitdown import MarkItDown md = MarkItDown() print(md.convert("data.xlsx").markdown)

服务端环境建议改用convert_local()，只处理本地文件——convert()设计上接受本地文件、远程 URI 和字节流，入口是故意做得宽的。

🔁 批量转换。没有专门的目录模式，套一层循环就行：

for f in *.pdf; do markitdown "$f" -o "out/${f%.pdf}.md" done

它逐个转当前目录下的 PDF，输出同名.md到out/里。

插件机制。先看已装了什么，再加-p启用：

markitdown --list-plugins markitdown document.pdf -p

官方 markitdown-ocr 插件（packages/markitdown-ocr/）能给 PDF、Word、PPT、Excel 转换器加 OCR 能力。Python API 里传入llm_client和llm_model，它就读出文档里嵌入图片中的文字——扫描件走这条路；不传llm_client时 OCR 环节静默跳过，交回内置转换器照常完成，转换不会失败。新格式也一般走插件路线，官方开发模板在 packages/markitdown-sample-plugin/，核心是实现accepts()和convert()两个方法再注册入口点。

云端端点（可选）。⚠️ 对复杂表格、扫描 PDF 需要更高质量提取时，加-d接 Azure Document Intelligence，或--use-cu接 Azure Content Understanding，都是付费云 API；内置转换器才是默认的免费本地路径。

参数速查

它做不到什么

• 扫描版 PDF：内置转换器只读文字层，纯图片页面转出空内容。加 markitdown-ocr 插件并传 LLM 客户端，或接云端端点。
• 排版还原：输出服务文本分析，别拿它做出版级文档转换，那种需求找专业排版工具。
• 不受信任的输入：它按当前进程权限做 I/O，和open()、requests.get()一个性质。服务端应用若输入可能来自用户，先做校验，优先调最窄入口convert_local()，别直接喂convert()。
• 视频：内置转换器没有视频支持，需要 Azure Content Understanding 端点。
• 缺可选依赖：没装对应 extra（如[xlsx]）时该格式直接不可用，报转换失败，别误判为文件损坏。

要本地、离线、结构化 Markdown——选 markitdown；要还原版式或处理扫描件——换专业排版工具或 OCR 插件，别硬扛。

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown