返回 导航

其他

hangge.com

MarkItDown - 免费的文档转Markdown工具安装使用详解（pdf、docx、ppt等）

作者：hangge | 2026-09-18 08:51
    在 大模型 时代，我们经常需要把 PDF、Word、PPT、Excel 等各种文档"喂"给 LLM 进行内容分析、知识索引或者智能问答。但这些二进制格式并不能直接被模型"消化"，需要先转换成 Markdown 这种大模型最友好的纯文本格式。本文我将给大家介绍一款微软官方开源的转换利器：MarkItDown，通过一个命令就能把各种常见文档统统变成 Markdown。

一、基本介绍

1，MarkItDown 是什么

（1）MarkItDown 是微软 AutoGen 团队开源的一款 Python 工具，用于将各类文件转换为 Markdown 格式（例如用于索引、文本分析、RAG 知识库构建等场景）。项目于 2024 年 12 月发布，上线后迅速冲上 GitHub Trending 榜首，目前 Star 数已超过 17 万，采用 MIT 开源协议。

（2）MarkItDown 的定位是一个轻量级的转换工具，对标的是老牌的 textract。区别在于：textract 只做纯文本提取，而 MarkItDown 会尽量保留文档的重要结构和内容——包括标题、列表、表格、链接等，输出的是一份结构完好的 Markdown，这对后续 LLM 的理解非常关键。

（3）它的核心特点如下：
  • 格式覆盖广：Office 全家桶、PDF、图片、音频、HTML、压缩包，甚至 YouTube 视频都能转；
  • 结构保留好：标题、列表、表格、链接等文档结构会转换为对应的 Markdown 语法，而不是丢成一坨纯文本；
  • 使用方式灵活：既可以作为命令行工具一条命令搞定，也可以作为 Python 库嵌入到我们自己的项目中，还提供了 MCP 服务器包供 AI 应用调用；
  • 插件生态：支持第三方插件扩展新的转换能力。

2，支持的文件格式

（1）MarkItDown 目前支持转换的格式如下：
  • PDF 文件
  • PowerPoint（pptx）文件
  • Word（docx）文件
  • Excel（xlsx / xls）文件
  • 图片（EXIF 元数据提取和 OCR）
  • 音频（EXIF 元数据提取和语音转录，支持 wav、mp3）
  • HTML 页面
  • 文本类格式（CSV、JSON、XML）
  • ZIP 压缩包（自动遍历包内文件逐个转换）
  • YouTube 视频 URL（自动获取字幕转录文本）

（2）可以看到，常见办公文档基本一网打尽。其中音频转录和 YouTube 字幕获取这两个能力特别实用，等于顺手把语音转文字的需求也覆盖了。
提示：MarkItDown 的输出主要面向文本分析工具和 LLM 消费。虽然输出结果通常也具有良好的可读性，但如果追求高保真的文档排版还原（比如转换后直接给人阅读的正式文档），它可能不是最佳选择。

二、安装配置

1，环境要求

MarkItDown 对环境的要求非常简单，只有一条 Python 版本的硬性规定，其余都是建议项：
  • Python 版本：3.10 或更高版本（硬性要求，低版本无法安装）；
  • 操作系统：Windows、macOS、Linux 均可；
  • 依赖策略：各文件格式的依赖被组织为可选功能组，安装时可按需选择（见本文末尾附录部分）。

2，安装步骤

（1）首先创建并激活一个虚拟环境（可选步骤，但强烈建议）：
提示：官方强烈建议在虚拟环境中安装使用，避免 MarkItDown 的依赖与我们系统里其它 Python 项目的依赖产生冲突。
# Windows（PowerShell）
python -m venv markitdown-env
markitdown-env\Scripts\activate

# macOS / Linux
python3 -m venv markitdown-env
source markitdown-env/bin/activate

（2）接着执行如下命令安装 MarkItDown：
提示：这里一定要带上 [all] 可选依赖组。从 0.1.0 版本开始，MarkItDown 把各格式的依赖拆分成了可选功能组，如果直接执行 pip install markitdown，只会安装核心部分，转换 PDF、Word 等文件时就会报依赖缺失错误。
pip install 'markitdown[all]'

（3）安装完成后执行如下命令，能看到命令帮助信息就表示安装成功了：
markitdown --help

三、使用样例

1，命令行方式转换文件

（1）最基础的用法，在 markitdown 命令后面直接跟上文件路径，转换结果默认输出到控制台，我们可以通过重定向保存到文件：
markitdown path-to-file.pdf > document.md

（2）也可以使用 -o 参数直接指定输出文件，效果一样但更直观：
markitdown path-to-file.pdf -o document.md

2，Python API 方式转换文件

（1）如果想在项目中集成转换能力，直接导入 MarkItDown 类，调用 convert() 方法即可：
from markitdown import MarkItDown

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

（2）转换结果是一个结果对象，其中 markdown 属性就是转换后的 Markdown 文本，title 属性是提取到的文档标题（如果有）。我们也可以直接把结果写入文件：
with open("output.md", "w", encoding="utf-8") as f:
    f.write(result.markdown)

3，转换 YouTube 视频字幕

（1）MarkItDown 还支持直接传入 YouTube 视频链接，自动抓取视频的字幕转录文本，这个功能拿来整理视频笔记、做课程文字稿特别好用：
提示：转换 YouTube 视频需要先安装 youtube-transcription 可选依赖组：pip install 'markitdown[youtube-transcription]'
markitdown https://www.youtube.com/watch?v=xxxxxx -o video.md

附、进阶用法

1，按需安装可选依赖

（1）[all] 会安装所有格式的依赖，体积较大。如果只需要转换某几种格式，可以按需安装对应的依赖组，例如只转换 PDF、Word 和 PPT：
pip install 'markitdown[pdf, docx, pptx]'

（2）目前支持的可选依赖组如下：
依赖组说明
[all]安装全部可选依赖（推荐，功能最完整）
[pdf]PDF 文件转换依赖
[docx]Word 文件转换依赖
[pptx]PowerPoint 文件转换依赖
[xlsx]Excel 文件转换依赖
[xls]旧版 Excel（.xls）文件转换依赖
[outlook]Outlook 邮件（.msg）转换依赖
[audio-transcription]音频语音转录依赖（wav、mp3）
[youtube-transcription]YouTube 视频字幕获取依赖
[az-doc-intel]Azure 文档智能（Document Intelligence）转换依赖
[az-content-understanding]Azure Content Understanding 转换依赖

2，作为 MCP 服务器接入到 AI 应用中

（1）MarkItDown 官方还提供了 MCP（Model Context Protocol）服务器包 markitdown-mcp，可以把文档转换能力直接集成到 Claude Desktop 这类支持 MCP 协议的 AI 应用中，让 AI 直接帮我们读文档。官方推荐使用 Docker 镜像方式运行，首先克隆仓库并构建镜像：
git clone https://github.com/microsoft/markitdown.git
cd markitdown
docker build -t markitdown-mcp:latest -f packages/markitdown-mcp/Dockerfile .

（2）然后在 Claude Desktop 的配置文件 claude_desktop_config.json 中添加如下配置，重启应用即可：
提示：默认配置只能访问远程 URL。如果需要让容器读取本地文件，要在 args 中追加目录挂载参数："-v"，"/home/user/data:/workdir"，这样容器内就能通过 /workdir 路径访问宿主机文件了。
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
    }
  }
}
评论

全部评论（0）

回到顶部