MarkItDown

[!TIP] MarkItDown 现在提供了一个 MCP（模型上下文协议）服务器，用于与 Claude Desktop 等 LLM 应用程序集成。更多信息请参阅 markitdown-mcp。

[!IMPORTANT] 0.0.1 到 0.1.0 之间的重大变更：

• 依赖项现在被组织为可选的功能组（详情见下文）。若需保持向后兼容性，请使用 pip install 'markitdown[all]'。
• convert_stream() 现在需要一个二进制文件类对象（例如以二进制模式打开的文件或 io.BytesIO 对象）。这是对先前版本的重大更改，因为之前它也接受文本文件类对象，如 io.StringIO。
• DocumentConverter 类的接口已更改为从文件类流中读取，而非文件路径。不再创建临时文件。如果您是插件或自定义 DocumentConverter 的维护者，可能需要更新您的代码。否则，如果仅使用 MarkItDown 类或 CLI（如本示例所示），则无需进行任何更改。

MarkItDown 是一款轻量级的 Python 工具，用于将各种文件转换为 Markdown 格式，以便在 LLM 和相关文本分析流水线中使用。在这方面，它与 textract 最为相似，但更注重以 Markdown 格式保留文档的重要结构和内容（包括：标题、列表、表格、链接等）。虽然输出通常具有较好的可读性和人性化呈现效果，但它主要是供文本分析工具消费的——对于需要高保真度的人类阅读文档转换来说，可能并不是最佳选择。

目前，MarkItDown 支持以下格式的转换：

• PDF
• PowerPoint
• Word
• Excel
• 图片（EXIF 元数据和 OCR）
• 音频（EXIF 元数据和语音转录）
• HTML
• 文本格式（CSV、JSON、XML）
• ZIP 文件（遍历其内容）
• YouTube 视频链接
• EPUB
• ……以及更多！

为什么选择 Markdown？

Markdown 非常接近纯文本，几乎没有标记或格式化，但仍能表示文档的重要结构。主流 LLM，例如 OpenAI 的 GPT-4o，原生支持 Markdown，并且经常会在未被提示的情况下在其响应中加入 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
# 注意：请务必使用 'uv pip install' 而不是 'pip install' 来安装此虚拟环境中的包

如果您使用 Anaconda，可以这样创建虚拟环境：

conda create -n markitdown python=3.12
conda activate markitdown

安装

要安装 MarkItDown，可以使用 pip：pip install 'markitdown[all]'。或者您也可以从源码安装：

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

使用方法

命令行

markitdown path-to-file.pdf > document.md

或者使用 -o 指定输出文件：

markitdown path-to-file.pdf -o document.md

您还可以通过管道输入内容：

cat path-to-file.pdf | markitdown

可选依赖

MarkItDown 具有用于启用各种文件格式的可选依赖项。在本文前面，我们使用 [all] 选项安装了所有可选依赖项。不过，您也可以单独安装它们以获得更高的控制权。例如：

pip install 'markitdown[pdf, docx, pptx]'

将只安装 PDF、DOCX 和 PPTX 文件所需的依赖项。

目前，可用的可选依赖项如下：

• [all] 安装所有可选依赖项
• [pptx] 安装 PowerPoint 文件所需的依赖项
• [docx] 安装 Word 文件所需的依赖项
• [xlsx] 安装 Excel 文件所需的依赖项
• [xls] 安装旧版 Excel 文件所需的依赖项
• [pdf] 安装 PDF 文件所需的依赖项
• [outlook] 安装 Outlook 邮件所需的依赖项
• [az-doc-intel] 安装 Azure Document Intelligence 所需的依赖项
• [audio-transcription] 安装用于 WAV 和 MP3 文件音频转录的依赖项
• [youtube-transcription] 安装用于获取 YouTube 视频转录的依赖项

插件

MarkItDown 还支持第三方插件。默认情况下，插件是禁用的。要列出已安装的插件：

markitdown --list-plugins

要启用插件，请使用：

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

要查找可用的插件，可以在 GitHub 上搜索标签 #markitdown-plugin。要开发插件，请参阅 packages/markitdown-sample-plugin。

markitdown-ocr 插件

markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 转换器增加了 OCR 支持，利用 LLM Vision 从嵌入式图像中提取文本——这与 MarkItDown 已经用于图像描述的 llm_client / llm_model 模式相同。无需新的机器学习库或二进制依赖。

安装：

pip install markitdown-ocr
pip install openai  # 或任何与 OpenAI 兼容的客户端

使用：

传递您用于图像描述的相同 llm_client 和 llm_model：

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)

如果没有提供 llm_client，插件仍然会加载，但 OCR 将被静默跳过，转而使用标准内置转换器。

详细文档请参阅 packages/markitdown-ocr/README.md。

Azure Document Intelligence

要使用 Microsoft Document Intelligence 进行转换：

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

有关如何设置 Azure Document Intelligence 资源的更多信息，请参阅 此处。

Python API

Python 中的基本用法：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # 设置为 True 以启用插件
result = md.convert("test.xlsx")
print(result.text_content)

Python 中的文档智能转换：

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

要使用大型语言模型生成图像描述（目前仅支持 pptx 和图像文件），请提供 llm_client 和 llm_model：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_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

贡献说明

本项目欢迎各种贡献和建议。大多数贡献都需要您签署贡献者许可协议（CLA），声明您有权且确实授予我们使用您贡献的权利。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记您的 PR（例如状态检查、评论）。您只需按照机器人提供的指示操作即可。对于所有使用我们 CLA 的仓库，您只需完成一次此步骤。

本项目已采用 微软开源行为准则。更多信息请参阅 行为准则常见问题解答，或如有任何其他疑问或意见，请联系 opencode@microsoft.com。

如何贡献

您可以查看问题或帮助审查 PR 来提供帮助。任何问题或 PR 都受欢迎，但我们也将一些标记为“开放贡献”和“开放评审”，以促进社区参与。当然，这些只是建议，您也可以以任何您喜欢的方式进行贡献。

运行测试和检查

• 导航到 MarkItDown 包：

  cd packages/markitdown
  

• 在您的环境中安装 hatch 并运行测试：

  pip install hatch  # 安装 hatch 的其他方法：https://hatch.pypa.io/dev/install/
  hatch shell
  hatch test
  

  （替代方案）使用已安装所有依赖项的 Devcontainer：

  # 在 Devcontainer 中重新打开项目并运行：
  hatch test
  

• 在提交 PR 之前运行预提交检查：pre-commit run --all-files

贡献第三方插件

您还可以通过创建和分享第三方插件来做出贡献。更多详情请参阅 packages/markitdown-sample-plugin。

商标说明

本项目可能包含项目、产品或服务的商标或标识。未经授权使用微软商标或标识须遵守并遵循 微软商标与品牌指南。在本项目的修改版本中使用微软商标或标识不得造成混淆或暗示微软的赞助。任何第三方商标或标识的使用均应遵守该第三方的相关政策。

MarkItDown 快速上手指南

MarkItDown 是一个轻量级 Python 工具，专为将各类文件（PDF、Office 文档、图片、音频等）转换为 Markdown 格式而设计，特别适用于大语言模型（LLM）的数据预处理和分析流程。

环境准备

• 系统要求：Python 3.10 或更高版本
• 推荐环境：建议使用虚拟环境以避免依赖冲突

创建并激活虚拟环境（任选一种方式）：

# 标准 Python 方式
python -m venv .venv
source .venv/bin/activate  # Windows 使用：.venv\Scripts\activate

# 或使用 uv（更快速）
uv venv --python=3.12 .venv
source .venv/bin/activate

# 或使用 Conda
conda create -n markitdown python=3.12
conda activate markitdown

💡 国内加速建议：如下载缓慢，可配置国内镜像源

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

安装完整功能版本（包含所有可选依赖）：

pip install 'markitdown[all]'

或从源码安装：

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

如需精简安装，可按需选择特定格式支持：

# 仅安装 PDF、Word 和 PowerPoint 支持
pip install 'markitdown[pdf,docx,pptx]'

可用选项包括：[pdf], [docx], [pptx], [xlsx], [xls], [outlook], [audio-transcription], [youtube-transcription] 等。

基本使用

命令行使用

转换单个文件并输出到终端：

markitdown path-to-file.pdf

转换文件并保存为 .md 文件：

markitdown path-to-file.pdf -o document.md

通过管道处理内容：

cat path-to-file.pdf | markitdown > document.md

Python API 使用

基础转换示例：

from markitdown import MarkItDown

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

启用插件支持（如第三方扩展）：

md = MarkItDown(enable_plugins=True)
result = md.convert("document_with_images.pdf")
print(result.text_content)

结合大模型进行图片描述（需安装 openai 或其他兼容客户端）：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

✅ 提示：转换结果保留标题、列表、表格、链接等结构信息，适合直接输入 LLM 进行进一步分析。