markitdown 完整教程：一条命令把 PDF、Word、EPUB 转成 Markdown

markitdown 完整教程：一条命令把 PDF、Word、EPUB 转成 Markdown

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

markitdown 是微软开源的 Python 转换工具，一条命令把PDF、Word、PPT、Excel、EPUB、图片、音频转成保留标题、表格、列表结构的 Markdown，专为大模型问答和文本分析流水线设计。本教程带你完成安装、跑通第一条转换命令，并掌握 Python API、OCR 插件与批量用法。

先判断：markitdown 适不适合你的场景

• 适合：文档要喂给大模型、建知识库、批量整理 Office 文件——这是它的核心活，输出天然省 token。
• 适合：文件不能出本地。内置转换路径完全离线，不经过任何服务器。
• 不适合：像素级排版还原。官方定位写得很清楚，输出是给文本分析工具消费的，不是给你二次出版用的。
• 先留意：扫描版 PDF。内置转换器只读文字层，纯图片页面会转出空内容，需要 OCR 插件或云端端点。
• 先留意：要求 Python3.10 到 3.14，装之前先python --version确认环境。

3 步上手：从零到第一条 markitdown 转换命令

第 1 步，创建虚拟环境并安装。避免依赖冲突，推荐 venv：

python -m venv .venv source .venv/bin/activate pip install "markitdown[all]"

[all]一次性装齐 PDF、Office、音频转录等所有可选依赖，装完你同时获得markitdown命令行工具和 Python 包。

第 2 步，想只装部分格式？按需选装更轻：

pip install "markitdown[pdf,docx]"

可选组完整清单在 pyproject.toml：pptx、docx、xlsx、xls、pdf、outlook、audio-transcription、youtube-transcription、az-doc-intel、az-content-understanding。

第 3 步，跑第一条命令。任何受支持的文件都是这个姿势：

markitdown report.pdf -o report.md

不加-o时结果直接打印到终端，适合快速预览；加-o则写入report.md。想从源码玩，先git clone https://gitcode.com/GitHub_Trending/ma/markitdown再pip install -e "packages/markitdown[all]"即可。

场景实战：按任务用 markitdown

把 PDF 论文和网页转成结构化文本喂给大模型

PDF 论文、Word 合同、HTML 网页、CSV/JSON/XML 都能转，管道输入也支持：

cat example.pdf | markitdown

它从标准输入读字节流并自动嗅探格式；格式识别不准时可用-x、-m、-c手动提示扩展名、MIME 类型和编码。下面是仓库测试素材里的一页学术论文，markitdown 转完后标题、作者行、摘要都会变成结构化文本，而不是糊成一坨：

注意它针对的是带文字层的数字 PDF；纯扫描的纸质 PDF 见后面的插件部分。

Excel 表格和 PPT 幻灯片变成可检索的 Markdown

命令不变，换文件名即可：

markitdown report.xlsx -o report.md

Excel 自动变成 Markdown 表格，PPT 按幻灯片逐张切分，Word 保留标题层级，Word 里的公式会转成LaTeX 写法（转换逻辑在 converter_utils/docx/math/omml.py）。会议纪要、财务报表批量进文本库后可以直接全文检索，不用打开 Office 软件。

图片提元数据、音频转文字、LLM 生成图片描述

图片会提取EXIF 元数据（设备、拍摄时间、坐标）输出成 Markdown 字段；wav、mp3 可以转录成文字（需[audio-transcription]依赖）；YouTube 链接能直接传，抓字幕后转换（需[youtube-transcription]依赖）。

上面这张是仓库里专门测 LLM 图片描述能力的样本——如果构造MarkItDown时传入了llm_client和llm_model，转换图片文件时会顺带生成一句描述。

进阶用法：Python API、插件与批量

3 行 Python API 把 markitdown 接进自动化流程

写自动化脚本时用代码调，核心就三行：

from markitdown import MarkItDown md = MarkItDown() print(md.convert("data.xlsx").markdown)

服务端环境建议改用convert_local()，只处理本地文件——convert()设计上会接受本地文件、远程 URI 和字节流，入口是故意做得宽的，需要更多控制还有convert_stream()、convert_response()可选（实现在 _markitdown.py）。

插件、批量与 MCP：三条扩展路线

批量转换没有专门的目录模式，套一层循环就行，逐个转当前目录的 PDF，输出同名.md到out/：

for f in *.pdf; do markitdown "$f" -o "out/${f%.pdf}.md" done

插件扩展：插件默认不启用，先markitdown --list-plugins看已装了什么，再加--use-plugins（或-p）启用。官方 markitdown-ocr 插件能给 PDF、Word、PPT、Excel 转换器加 OCR 能力，用 LLM Vision 读出文档里嵌入图片中的文字——扫描件文档就走这条路。pip install markitdown-ocr之后，Python 侧这样配：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown(enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o") print(md.convert("scanned.pdf").markdown)

没传llm_client时 OCR 会被静默跳过，回退到内置转换器，不会报错。新格式也建议走插件路线，官方模板在 packages/markitdown-sample-plugin/，核心就是实现accepts()和convert()两个方法再注册入口点。

MCP 集成：packages/markitdown-mcp/ 提供一个 MCP 服务器，暴露convert_to_markdown(uri)工具，支持 STDIO 与 HTTP 传输，pip install markitdown-mcp后直接markitdown-mcp启动，方便接进 Claude Desktop 等 MCP 客户端。

markitdown 参数速查表与同类方案对比

和同类方案横向比一下：

5 种 markitdown 搞不定的情况与对策

• 扫描版 PDF 转出空内容：内置转换器只读文字层。加 markitdown-ocr 插件配 LLM 客户端，或-d/--use-cu接云端端点。
• 出版级排版还原：做不到，输出服务文本分析。这种需求找专业排版工具，别硬扛。
• 服务端喂不受信任的输入：它按当前进程权限做 I/O，和open()、requests.get()一个性质。先做输入校验，并优先调convert_local()这类最窄入口，别直接喂convert()。
• 视频文件：内置转换器没有视频支持，只能走 Azure Content Understanding 端点（--use-cu）。
• 某格式直接报转换失败：多半是没装对应可选依赖（如[xlsx]）。装上对应依赖组再试，别误以为是文件坏了。

本地、离线、要结构化 Markdown 进大模型——选 markitdown，pip install "markitdown[all]"就能覆盖绝大多数场景；要还原版式就换专业排版工具，要处理扫描件就加 OCR 插件或云端点，两条路都清晰，不用纠结。

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