markitdown：各类文档转 Markdown 的 Python 工具

微软开源的 markitdown 是一款将多种文件格式转换为 Markdown 的 Python 工具，目前获得 142,649 个 Star。它的设计目标是为大语言模型和文本分析流程提供结构化的 Markdown 输出，保留文档的标题、列表、表格和链接等关键结构。

支持的格式

markitdown 目前支持的输入格式包括 PDF、PowerPoint、Word、Excel、图片、音频、HTML、CSV、JSON、XML、ZIP、YouTube 链接和 EPub。其中图片转换会提取 EXIF 元数据并进行 OCR 识别，音频转换则会提取元数据并进行语音转录。ZIP 文件会被递归遍历内部内容并分别转换。

工具要求 Python 3.10 或更高版本。安装命令为 pip install markitdown，也可以加上 [all] 参数安装全部可选依赖，或者按格式选择部分依赖，如 [pdf, docx, pptx]。

基本用法

命令行用法直接明了：

markitdown path/to/file.pdf > output.md

Python API 的调用方式同样简单：

from markitdown import MarkItDown
md = MarkItDown()
result = md.convert(“file.xlsx”)
print(result.text_content)

markitdown 支持通过 llm_client 和 llm_model 参数接入大语言模型，用于图片内容的描述和识别，当前这项功能主要针对 PPTX 和图片文件。

插件与扩展

markitdown 支持第三方插件机制，默认关闭。可以通过 markitdown --list-plugins 查看已安装的插件，用 --use-plugins 参数启用。开发者还可以基于 packages/markitdown-sample-plugin 中的模板创建自定义插件。

目前已有的 markitdown-ocr 插件利用 LLM Vision 能力为 PDF、DOCX、PPTX 和 XLSX 转换器增加 OCR 支持，从嵌入的图片中提取文字，无需引入额外的机器学习库。

对于企业级场景，markitdown 集成了 Azure Content Understanding 和 Azure Document Intelligence。Content Understanding 提供更高质量的云端转换，支持视频文件、结构化字段提取和自定义分析器。Document Intelligence 则提供云端布局分析和 OCR 能力，适合扫描版 PDF 和复杂表格的处理。

安全提示

markitdown 在执行 I/O 操作时使用的权限与当前进程相同。它会访问进程本身能够访问的资源，因此在不受信任的环境中需要谨慎处理输入数据。建议调用最窄范围的转换函数，例如仅需本地文件时使用 convert_local()，需要流式处理时使用 convert_stream()。

定位与适用场景

markitdown 的输出主要面向文本分析工具消费，侧重于保留文档结构和内容，而非追求高保真的人类可读排版。对于日常文档的格式统一、知识管理体系建设，以及为大语言模型准备训练数据等场景，它提供了一套实用且覆盖全面的解决方案。项目采用 MIT 协议开源，并接受社区贡献。

场景，它提供了一套实用且覆盖全面的解决方案。项目采用 MIT 协议开源，并接受社区贡献。