markitdown 完整指南：一条命令把 PDF、Word、EPUB 转成 Markdown

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

markitdown 是微软开源的 Python 转换工具，把PDF、Word、PPT、Excel、EPUB、图片、音频等文件转成保留结构的 Markdown。读完这篇文章，你能装好它、跑通第一条转换命令，并按任务场景知道它的边界在哪。

30 秒判断：该不该用它

• 用它：文档要进大模型问答、建知识库，或者批量整理 Office 文件——这是它的核心活。
• 用它：文件不能出本地。默认转换路径完全离线，不经过任何服务器。
• 别指望它：像素级排版还原。官方定位写得很清楚，输出是给文本分析工具消费的，不是给你二次出版用的。
• 留意：扫描版 PDF。内置转换器只读文字层，读不到页面里的图，需要加 OCR 插件或接云端端点。
• 留意：Python 版本要求 3.10 到 3.14，装之前先确认环境。

三步跑通：安装、第一条命令、看结果

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

pip install "markitdown[all]"

装完后你获得markitdown命令行工具和 Python 包。只想要某几种格式可以按需装，比如pip install "markitdown[pdf,docx]"就只覆盖 PDF 和 Word。想从源码玩：

git clone https://gitcode.com/GitHub_Trending/ma/markitdown pip install -e "packages/markitdown[all]"

第二步，跑第一条命令。任何受支持的文件都这样转：

markitdown book.epub -o book.md

它读文件、按格式选转换器、把结果写进book.md；不加-o时结果直接打印到终端，适合快速预览。

第三步，看结果。打开book.md你会发现顶部多了几行加粗字段：markitdown 会解析 EPUB 里的 content.opf，把书名、作者、出版社等元数据自动带出来放在正文前面。转 PDF、Word 也一样，标题、列表、表格都变成对应的 Markdown 结构，而不是糊成一大段文字。

能力地图：按任务分组看

把文档喂给大模型问答

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

cat example.pdf | markitdown

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

注意它针对的是带文字层的数字 PDF；纯扫描的纸质 PDF 见后面的插件部分。

把表格和幻灯片变成可检索的纯文本

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

markitdown report.docx -o report.md

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

抽取图片元数据、转录音频

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

像上面这种测试图，如果你传入了 LLM 客户端，markitdown 还能顺带生成一句图片描述——这张图就是项目里专门测这个能力的样本。

进阶玩法：API、批量与插件

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

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

服务端环境建议改用convert_local()，只处理本地文件，比默认入口convert()更安全——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 插件 能给 PDF、Word、PPT、Excel 转换器加 OCR 能力，配合 LLM 客户端读出文档里嵌入图片中的文字——扫描件文档就走这条路；没传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 端点。
• 格式支持按需装配：没装对应可选依赖（如[xlsx]）时该格式直接不可用，报的是转换失败，别误以为是文件坏了。

本地、离线、要结构化 Markdown 进大模型——选 markitdown，装[all]就能覆盖绝大多数场景；要还原版式或处理扫描件，再分别换专业排版工具或加 OCR 插件，别硬扛。

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