markitdown：3 步免费把 PDF、Word、EPUB 转成 Markdown

markitdown：3 步免费把 PDF、Word、EPUB 转成 Markdown

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

你有一堆想喂给大模型、或整理进笔记的 PDF、Word 和电子书，复制粘贴却总是把格式弄乱。markitdown 是一个免费、本地运行的 Python 工具，一条命令就能把 PDF、Word、EPUB 等十几种文件转成结构化 Markdown，标题、列表、表格尽量保留，文件不出你的机器。

三步跑通第一次转换 ⚡

第 1 步：确认 Python 版本。markitdown 要求 Python 3.10 及以上：

python3 --version

低于 3.10 会直接安装失败，先换成 venv、uv 或 conda 搭的 3.12 环境再往下走。

第 2 步：安装。建议一次性装全可选依赖：

pip install 'markitdown[all]'

也可以按格式单独装（如markitdown[pdf, docx]），但这步省了，转文件报错时你还会回来补。

第 3 步：第一次转换。把文件路径给它，结果打到终端；写-o document.md则是直接存文件：

markitdown your-file.pdf > document.md

最后执行markitdown --version验证：能打印出版本号，就算装好了。

支持格式一览

其中图片转换是亮点：markitdown 能把图里的视觉内容写成文字描述。下面这张图来自仓库自带的测试素材，展示的正是这个场景：

如果想要更高品质的云端提取，还可以装[az-doc-intel]或[az-content-understanding]接上 Azure 服务。

实战：把 EPUB 电子书转成 Markdown

仓库里自带一本真实的测试电子书 test.epub，全程不到 30 秒。执行markitdown test.epub -o mybook.md，mybook.md就是转换结果。真实输出（摘自仓库的测试预期）长这样：

**Authors:** Test Author # Chapter 1: Test Content This is a **test** paragraph with some formatting * A bullet point

有两个细节值得注意：

• **Authors:**这类字段和描述行，是 markitdown 从 EPUB 内部元数据里自动抽出来的，等于顺手帮你生成了著录信息；
• 章节按书里声明的阅读顺序（spine）依次拼接，标题、加粗、列表、引用都转成了 Markdown 语法，整本合并成一个文件。

小知识：EPUB 本质是个 ZIP 包。markitdown 会先读取包内的描述文件（OPF），再按 spine 顺序逐章取出 XHTML 内容转换，所以常规结构的 EPUB 都能正常处理。

Python API 与批量处理写法

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

convert()换个文件名就能切换任意受支持格式，写批量脚本时放进循环即可处理整个目录。管道输入没有扩展名时，可以把字节流传给convert_stream()，CLI 里则用-x补一个格式提示。

markitdown 不擅长什么

• ⚠️不追求高保真版式还原。官方定位是"面向文本分析和 LLM 的转换"，输出给人看基本可读，但逐像素还原排版它不是首选。
• 内置转换器不支持视频。视频要走 Azure Content Understanding（装[az-content-understanding]）。
• 新格式加入很保守。项目建议新格式走第三方插件：仓库里带了示例 packages/markitdown-sample-plugin/，另有独立的 OCR 增强包 packages/markitdown-ocr/。

适合你，如果：

• 你经常要把文档变成笔记或喂给大模型；
• 你在写自动化管道：抓文档 → 转 Markdown → 入库。

不太适合，如果：

• 你要的是像素级还原、可编辑的版式；
• 偶尔只转一两个小文件，在线工具更快。

常见报错速查

• 转 PDF 报缺依赖→ 没装对应依赖组 → 一开始就pip install 'markitdown[all]'。
• 安装失败、提示 Python 版本→ markitdown 要求 3.10 及以上 → 升级，或用 venv、uv 建 3.12 环境。
• cat file | markitdown认不出格式→ 管道输入没有扩展名 → 加-x pdf给提示。
• wav/mp3 转不出语音内容→ 缺[audio-transcription]组 → 装上再转。
• 第三方插件不生效→ 插件默认是关闭的 →--list-plugins查看已装的，再带-p启用。
• 服务器场景传入不受信的文件路径→ markitdown 以当前进程权限做 I/O → 改用convert_local()、convert_stream()这类更窄的入口。

markitdown 做的只是"文件变 Markdown"这一小步，但它打通了文档、笔记和大模型之间的路：一条命令、本地免费、结构保留。今天就先把你手头最烦的那份文件转一遍，看看输出再决定下一步。

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