MarkItDown 完整教程：一键将 PDF、Word、PPT 等文件转成 Markdown 的免费 Python 工具

MarkItDown 完整教程：一键将 PDF、Word、PPT 等文件转成 Markdown 的免费 Python 工具

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown

你有没有这种经历：手里攥着一份 PDF 报告、一叠 Word 合同、几页 PPT 汇报，想喂给大模型做总结、做检索、做分析，却发现它们不是"纯文本"，模型根本读不进去。MarkItDown 就是来解决这件事的：一款免费开源的 Python 工具，能把 PDF、Word、PPT、Excel，甚至图片、音频、网页批量转成结构完整的 Markdown，标题、列表、表格、链接全都保留。装完一条命令就能跑，下面是完整上手指南。

🚀 核心价值速览

• 格式覆盖广：PDF、PowerPoint、Word、Excel、图片、音频、HTML、CSV/JSON/XML、ZIP、EPUB、YouTube 链接，一个工具全搞定
• 结构保真：不是简单导出文字，而是保留标题层级、列表、表格、链接等文档结构
• 对 LLM 友好：Markdown 本身就是大模型最"说"得顺的格式，转完即可直接进你的 RAG 或分析流水线
• 零配置起步：pip一条命令安装，CLI 一条命令转换，Python API 三行代码接入
• 可插拔扩展：第三方插件机制，按需加 OCR、加云提取服务，核心包保持轻量

📸 转换效果长什么样

下面是项目测试文件中的真实样例。左边这类文档页面，转换后标题、段落、图注都会变成规整的 Markdown 文本；右边这类图片，则能通过 LLM 生成描述文字。

⚡ 三步跑起来：安装 + 转换第一个文件

前提：需要 Python 3.10 或更高版本。建议使用虚拟环境，避免依赖冲突：

python -m venv .venv && source .venv/bin/activate

第 1 步：安装。最快路径是直接装全量依赖：

pip install 'markitdown[all]'

如果你偏好从源码安装（需要贡献代码或调试），克隆仓库后：

git clone https://gitcode.com/GitHub_Trending/ma/markitdown cd markitdown pip install -e 'packages/markitdown[all]'

第 2 步：转换第一个文件。命令行下输入你的文件路径即可：

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

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

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

第 3 步：打开document.md检查。标题、表格、链接都在，转换成功。

到这里，最短路径已经走完。下面挑最常用的几个功能细讲。

📝 核心功能实操

命令行转换的四种姿势

• 文件参数：markitdown example.pdf，结果打印到终端
• 管道输入：cat example.pdf | markitdown，适合脚本里串联处理
• 指定输出：markitdown example.pdf -o example.md
• 给格式提示：从 stdin 读入时不确定文件类型？加-x pdf提示扩展名，或用-m提示 MIME 类型、-c提示字符编码

按需安装格式依赖

[all]会装下所有格式支持，其实你可以只装需要的部分，环境更干净：

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

Python API 接入你的项目

三行代码把转换能力写进自己的程序：

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

用 LLM 描述图片内容

转换图片和 PPT 里的图片时，传入一个 LLM 客户端，它会自动为图片生成描述文字：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(llm_client=OpenAI(), llm_model="gpt-4o") print(md.convert("example.jpg").text_content)

🐳 进阶能力：Docker、MCP 服务与 OCR 插件

Docker 部署：项目根目录自带 Dockerfile，两条命令完成容器化：

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

MCP 服务化：如果你用 Claude Desktop 等 MCP 客户端，可以装markitdown-mcp包，它暴露一个convert_to_markdown(uri)工具，支持 STDIO / HTTP / SSE 三种传输方式，让 AI 助手直接帮你转文档。源码见 packages/markitdown-mcp/。

OCR 插件：扫描件、图片里的文字怎么办？社区插件markitdown-ocr用 LLM Vision 从 PDF、DOCX、PPTX、XLSX 内嵌图片中提取文字，扫描件会整页 300 DPI 渲染后识别。安装后加--use-plugins即可启用：

pip install markitdown-ocr openai markitdown scanned.pdf --use-plugins --llm-client openai --llm-model gpt-4o

插件机制：用markitdown --list-plugins查看已装插件，搜索标签#markitdown-plugin可以找到更多社区插件。想自己写一个？packages/markitdown-sample-plugin/ 提供了完整的 RTF 转换示例，照着改就行。

云提取服务：本地转换质量不够时，可以接 Azure Document Intelligence（-d参数）或 Azure Content Understanding（--use-cu参数），后者还支持音视频和结构化字段抽取，适合发票、收据这类领域文档。

所有格式的具体实现都集中在 packages/markitdown/converters/，想看某个格式怎么转的，直接翻这个目录。

⚙️ 配置参考

可选依赖组（pip install时按需挑选）：

常用命令行参数：

❓ 常见问题

Q：为什么转成 Markdown 而不是纯文本？A：Markdown 只比纯文本多一点点标记，却能完整表达标题、列表、表格结构，而主流大模型正是"泡"在海量 Markdown 里训练的，理解得最好，而且 token 效率更高。

Q：扫描版 PDF（整页是图片）能转吗？A：内置转换提取的是文档内嵌文字层，纯扫描件建议装markitdown-ocr插件走 LLM 视觉识别，或用 Azure 云提取服务。

Q：Python 版本有什么要求？A：3.10 及以上，Python 3.10~3.13 均在支持范围内。

Q：在服务器上做 Web 服务要注意什么？A：MarkItDown 以当前进程权限读写资源，不要直接把不可信输入喂给convert()。只读本地文件就用更窄的convert_local()，需要更强控制可以用convert_stream()。

Q：输出偶尔有人读起来不够美观，正常吗？A：正常。它的目标是喂给文本分析工具，保结构优先于保排版，不建议当作高保真排版转换工具用。

开始使用

MarkItDown 把"文档进、Markdown 出"压缩成了一条命令的距离：装完pip install 'markitdown[all]'，把文件路径丢给markitdown，你的大模型流水线就有了干净的结构化文本。现在就挑一份手头的 PDF 试试，剩下的交给它。

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown