microsoft/markitdown
开发工具把 PDF、Office 文档、HTML、音频等输入转换为 Markdown 的 Python 库和命令行工具,面向 LLM 与文本分析流程。
项目介绍
MarkItDown 是微软维护的 Python 工具,用于把各类文件转成 Markdown,供 LLM 提示词和文本分析流程使用。它支持 PDF、PowerPoint、Word、Excel、HTML、CSV/JSON/XML、EPUB、图片、音频、ZIP 压缩包和 YouTube URL 等格式,重点保留标题、列表、表格、链接等文档结构,而不是做面向人工阅读的高保真转换。输出通常可以直接阅读,但它的目标读者是文本分析工具。项目可从 PyPI 安装。
图片描述和语音转写依赖线上服务。关于 PDF,有讨论指出其实现封装了 PDFMiner;如果只需要提取 PDF,可以直接使用 PDFMiner(讨论,PDFMiner 文档)。
快速上手
运行需要 Python 3.10–3.14,建议先建虚拟环境以避免依赖冲突(前置条件)。
python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'
[all] 会安装全部格式的依赖。为了减小安装体积,也可以按需安装,例如 pip install 'markitdown[pdf,docx,pptx]'(可选依赖)。
命令行转换:
markitdown path-to-file.pdf > document.md
# 或直接写入文件
markitdown path-to-file.pdf -o document.md
# 或通过管道输入
cat path-to-file.pdf | markitdown
在 Python 中直接调用:
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.markdown)
如果本机装有 uv,2024 年的讨论中有人建议用 uvx markitdown path-to-file.pdf 免安装运行,首次运行会缓存依赖包(HN 评论)。这是社区用法,不是文档给出的安装方式。
云端与插件
需要更高质量地提取扫描 PDF、复杂表格,或处理音频、视频时,可以配合 Azure Content Understanding 使用:--use-cu --cu-endpoint "<content_understanding_endpoint>"。也支持 Azure Document Intelligence,命令行参数为 -d 和 -e "<document_intelligence_endpoint>",Python 端使用 docintel_endpoint。两者都是计费的 Azure 服务,部分可选分析功能还会额外收费(Document Intelligence 定价)。
第三方插件默认关闭,可用 markitdown --list-plugins 查看、markitdown --use-plugins 启用。独立的 markitdown-ocr 插件借助 LLM 视觉客户端,为 PDF、DOCX、PPTX、XLSX 中内嵌的图片增加 OCR(OCR 插件)。
使用约束
MarkItDown 以当前进程的权限进行 I/O,因此不可信输入在转换前必须校验。在托管或服务端应用中,应限制文件路径、URI 协议和网络目标,并拦截私有、回环、链路本地和元数据服务地址。优先使用最窄的接口:本地文件用 convert_local(),已获取的响应用 convert_response(),字节流用 convert_stream(),而不是权限更宽的 convert()(安全说明)。
图片描述、语音转写以及两个 Azure 集成都依赖外部线上服务;纯本地使用时应只安装自己需要的可选依赖。本仓库提供的是库和命令行工具,不是终端用户应用:Web 服务器、REST API、桌面或移动端界面明确不在范围内,新格式通常建议以第三方插件形式提供(贡献范围)。
HotRepo 点评
MarkItDown 在 2026-09-07 的 GitHub 全部语言日榜记录中约有 18 万 Star,当天新增约 0.8k;9 月 8 日和 9 日新增升至约 2.0k。2026-11-19 的 Python 语言日榜记录显示当天新增约 526 个 Star,在该榜的最好名次为第 10。这些记录来自不同榜单范围,不宜看作一条连续的涨势。2024 年的 Hacker News 讨论有 81 条评论;一位做过内部同类转换工具的评论者认为实现合理,但建议图片直接交给多模态模型,并避免用 Markdown 表格表达电子表格(HN 评论)。另一位评论者指出难点在脏文档的长尾:干净的 DOCX 转换很简单,截图和复杂表格则不是(HN 评论)。这与项目的定位一致:用一套通用流程覆盖多种格式,在提取质量要求更高时再引入云服务和插件。
本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。