MarkItDown 是一个轻量级 Python 工具包，可将 PDF、Word、Excel、PowerPoint、图片、音频等多种文件格式转换为 Markdown 格式，专为大语言模型和文本分析管道设计。该工具能够保留文档的重要结构和内容，包括标题、列表、表格、链接等元素。
核心功能与支持的格式
MarkItDown 支持将多种文件类型转换为 Markdown，主要功能包括：
- 文档格式：支持 PDF、Word、Excel、PowerPoint、EPubs 等文档文件的转换。
- 图片处理：提取图片的 EXIF 元数据，并支持 OCR 识别图片中的文字。
- 音频处理：支持 WAV 和 MP3 文件的语音转录，提取 EXIF 元数据。
- 网页与文本：支持 HTML 页面、CSV、JSON、XML 等文本格式的转换。
- 压缩包：可遍历 ZIP 文件内容并逐一转换。
- 视频平台：支持 YouTube 视频转写的获取。
为什么选择 Markdown
Markdown 格式接近纯文本，标记和格式化元素极少，但能清晰表达文档结构。主流大语言模型如 OpenAI 的 GPT-4o 原生支持 Markdown，能够自然理解并生成 Markdown 内容。此外，Markdown 的约定在 token 使用方面也具有高效优势。
前置要求与虚拟环境
MarkItDown 需要 Python 3.10 或更高版本。为规避依赖冲突，建议使用虚拟环境：
标准 Python 虚拟环境
使用以下命令创建并激活：
python -m venv .venv
source .venv/bin/activate使用 uv 创建
uv venv --python=3.12 .venv
source .venv/bin/activate使用 Anaconda
conda create -n markitdown python=3.12
conda activate markitdown安装方式
Pip 安装
通过 pip 安装所有可选依赖：
pip install 'markitdown[all]'或从源码安装：
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'命令行使用
基本转换
将文件转换为 Markdown 并输出到标准输出：
markitdown path-to-file.pdf > document.md使用 -o 参数指定输出文件：
markitdown path-to-file.pdf -o document.md通过管道传递内容：
cat path-to-file.pdf | markitdown可选依赖
MarkItDown 支持多种可选依赖以激活特定文件格式：
- [all]：安装所有可选依赖。
- [pptx]：PowerPoint 文件依赖。
- [docx]：Word 文件依赖。
- [xlsx]：Excel 文件依赖。
- [xls]：旧版 Excel 文件依赖。
- [pdf]：PDF 文件依赖。
- [outlook]：Outlook 邮件依赖。
- [audio-transcription]：WAV 和 MP3 音频转录依赖。
- [youtube-transcription]：YouTube 视频转写获取依赖。
例如，仅安装 PDF、DOCX 和 PPTX 依赖：
pip install 'markitdown[pdf, docx, pptx]'插件系统
MarkItDown 支持第三方插件，默认处于禁用状态：
- 查看已安装插件：markitdown –list-plugins
- 启用插件：markitdown –use-plugins path-to-file.pdf
- 在 GitHub 搜索标签 #markitdown-plugin 查找可用插件
- 插件开发参考：packages/markitdown-sample-plugin
MarkItDown OCR 插件
p>该插件为 PDF、DOCX、PPTX 和 XLSX 转换器添加 OCR 功能，通过集成大语言模型视觉功能提取嵌入图片中的文字。安装步骤如下：
pip install markitdown-ocr
pip install openai使用示例：
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(
enable_plugins=True,
llm_client=OpenAI(),
llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)Azure Document Intelligence
使用 Microsoft Document Intelligence 进行转换：
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"Python API 使用
基本示例
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)启用插件
md = MarkItDown(enable_plugins=True)接入大语言模型
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)Docker 使用
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md版本变更注意
0.0.1 到 0.1.0 重要变更
- 依赖现在按功能组组织，向后兼容需使用：pip install ‘markitdown[all]’
- convert_stream() 现在需要二进制文件对象（如 io.BytesIO），不再接受文本文件对象
- DocumentConverter 类接口从文件路径改为读取文件流，不再创建临时文件
贡献指南
参与方式
项目欢迎所有贡献和建议：查看 Issues 或帮助评审 Pull Requests。部分 Issue 标注为 “open for contribution” 或 “open for reviewing” 以方便社区参与。
运行测试
cd packages/markitdown
pip install hatch
hatch shell
hatch test提交 PR 前运行 pre-commit 检查：
pre-commit run --all-filesMarkItDown 通过轻量级设计和多格式支持，为大语言模型应用提供了便捷的文件转换方案，特别适合需要批量处理文档并进行文本分析的场景。