title: 📄 MarkItDown：128k Stars 的万能文件转 Markdown 工具，微软出品
slug: microsoft-markitdown
categories:
- category-ozfwcjgj
tags:
- Python
- Markdown
- Microsoft
- LLM
- File-Conversion
每次要给 LLM 喂材料的时候，最烦的就是文件格式不统一。PDF 里可能带表格，PPT 的文本层层嵌套，Excel 的数据你只想提取关键行——一个个手动整理又慢又容易漏。MarkItDown 就是来解决这个痛点的：一个 pip install 就能用的 Python 工具，把你能想到的常见文件格式全转成 Markdown，让 LLM 直接"吃"。
项目速览
- 项目：microsoft/markitdown
- Stars：128k ⭐（增长极快，已被广泛采用）
- Forks：8.8k
- 语言：Python（99.7%）
- 许可证：MIT
- 团队：微软 AutoGen 团队
- 最新版本：v0.1.6（2026年5月）
支持哪些格式？
MarkItDown 能处理 PDF、PowerPoint、Word、Excel、CSV、图片（OCR）、音频（语音转文字）、HTML、ZIP、EPUB、JSON、XML，甚至 YouTube 链接。基本上你日常办公和开发遇到的文档格式全覆盖了。
实操上手
1. 安装
一行命令搞定，建议用 [all] 装全量依赖：
pip install 'markitdown[all]'
如果只需要特定格式的支持，可以按需安装：
pip install 'markitdown[pdf, docx, pptx]'
2. CLI 命令行使用
最简单的用法，直接把 PDF 转成 Markdown 输出到文件：
markitdown report.pdf > report.md
也可以用 -o 指定输出路径：
markitdown report.pdf -o report.md
管道输入也支持：
cat report.pdf | markitdown
3. Python API 基础调用
在代码里集成只需三行：
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("report.pdf")
print(result.text_content)
4. 用 LLM 为图片自动生成描述
如果你有图片或 PPT 里有插图，可以接上 OpenAI 客户端让它自动写描述：
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("presentation.pptx")
print(result.text_content)
5. 用 Docker 运行
不想污染本地环境？直接用 Docker：
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
6. 启用 OCR 插件处理图片型文档
对于扫描件或 PDF 里的图片，可以安装 OCR 插件：
pip install markitdown-ocr
然后在代码里启用：
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(
enable_plugins=True,
llm_client=OpenAI(),
llm_model="gpt-4o",
)
result = md.convert("scanned_document.pdf")
print(result.text_content)
⚠️ 避坑提醒
- 安全第一：MarkItDown 会以当前进程权限执行 IO，不要直接喂不可信的输入文件，尤其是作为服务端使用时。建议用
convert_local()或convert_stream()替代万能的convert()。 - 不是给人看的：它的输出是给 LLM 消费的，格式保留标题/列表/表格/链接等结构，但排版审美就别指望了。
- 可选依赖多：
pip install markitdown（不加[all]）只装核心库，处理 PDF 或 Excel 前记得安装对应的 extras，不然会报找不到依赖。 - Python 版本要求：需要 Python 3.10+，老版本环境需要先升级。
要点总结
- 微软 AutoGen 团队出品，MIT 协议，128k Stars，生态活跃
pip install 'markitdown[all]'一键安装，菜鸟友好- CLI 和 Python API 双模式，集成到 LLM 预处理管道非常顺手
- 支持 PDF / PPT / Word / Excel / 图片 / 音频 / HTML / EPUB 等十余种格式
- 可接 OpenAI 等 LLM 为图片自动生成描述，OCR 插件支持扫描件
- 生产环境注意输入安全，用
convert_local()替代convert()