MarkItDown — 功能简介

MarkItDown 是一个轻量级的 Python 实用程序，可将许多常见文件类型转换为 Markdown —— 一种使用简单格式符号的纯文本格式，例如标题用 #，列表用 -，表格用 |。其输出专为 LLM（大语言模型） 和文本分析流水线设计，而非追求面向人类的高保真转换。

支持的文件类型

PDF
PowerPoint
Word
Excel
图像（提取 EXIF 元数据并运行 OCR 读取文本）
音频（提取 EXIF 元数据并转录音频）
HTML
基于文本的格式：CSV、JSON、XML
ZIP 文件（会迭代处理其中的内容）
YouTube URL
Epub
更多

为什么选择 Markdown？

Markdown 几乎是纯文本（标记极少），却能表示标题、列表、表格和链接等结构。现代 LLM 原生理解 Markdown，并且经常在输出中使用它，因此将 Markdown 输入给它们是很自然的选择。此外，Markdown 非常节省 token —— 比冗长的格式消耗更少的 AI token。

要求

需要 Python 3.10 至 3.14。
建议使用虚拟环境（标准 Python、uv 和 Anaconda 的命令见 README）。

安装

pip install 'markitdown[all]'

[all] 会拉取所有可选依赖。你也可以只安装需要的依赖，例如 pip install 'markitdown[pdf, docx, pptx]'。可选依赖组包括 [pdf]、[docx]、[pptx]、[xlsx]、[xls]、[outlook]、[az-doc-intel]、[az-content-understanding]、[audio-transcription] 和 [youtube-transcription]。

用法

命令行

markitdown path-to-file.pdf > document.md
# 或
markitdown path-to-file.pdf -o document.md
# 或通过管道输入
cat path-to-file.pdf | markitdown

Python API（基础）

from markitdown import MarkItDown

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

插件

第三方插件可以扩展 MarkItDown 支持新的格式。它们默认情况下禁用 —— 使用 --use-plugins 启用：

markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf

捆绑的 markitdown-ocr 插件使用 LLM 视觉模型（例如 GPT-4o）从 PDF/DOCX/PPTX/XLSX 内的图片中提取文本 —— 无需额外的机器学习库。如果未提供 llm_client，插件会加载但静默跳过 OCR。

高质量云端转换（可选）

Azure Content Understanding 为文档、图像、音频和视频提供更高质量的结果，并能将结构化字段（如发票金额）提取为 YAML front matter。每次转换都是一次计费的 Azure API 调用。

Azure Document Intelligence 是另一个适用于文档的云端选项。它可以使用自定义模型、启用分析附加功能（例如 OCR、样式检测）并提取查询字段。同样需要计费。

内置转换器是免费的（仅使用本地计算）。

安全警告

MarkItDown 以使用它的进程相同的文件系统和网络权限运行。不要向其提供不受信任的输入（例如在托管服务中）。清理路径、限制 URI 方案，并阻止访问私有/回环/元数据地址。

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

贡献指南

范围内： 转换器保真度改进、错误/性能/安全修复、CLI、markitdown-mcp 包、测试、文档、开发工具。 范围外： Web 服务器、REST/HTTP API、托管服务、Web 前端、桌面/移动应用。这些应作为依赖 PyPI 上 markitdown 的独立包。

新格式很少添加 —— 大多数新格式应通过第三方插件提供（在 GitHub 上标记 #markitdown-plugin）。

运行测试

cd packages/markitdown && pip install hatch && hatch shell && hatch test —— 或使用提供的 Devcontainer。提交 PR 前请运行 pre-commit run --all-files。

microsoft/markitdown