跳到主要内容
MarkItDown · prolist
查看仓库原始简介 Python tool for converting files and office documents to Markdown.
项目解读 README
项目解读由 AI 根据历史资料整理，尚未经人工复核。仓库资料更新于 2026-09-08，与历史解读分开保留。
项目概览 MarkItDown 是微软 AutoGen 团队开发并维护的开源 Python 工具，采用 MIT 协议，当前 GitHub 星标超过 105k，最新版本为 v0.1.5（2026 年 2 月发布）。它支持 PDF、Word、PowerPoint、Excel、图片、音频、HTML、EPUB 等 15 种以上文件格式，将其转换为结构化的 Markdown 文本。其核心设计目标是让 LLM 和文本分析工具能以最高效的方式“阅读”非文本文件，输出为机器可消费的结构化文本，而非人类可读的高保真转换。工具采用可插拔的 Converter 架构，每种格式对应独立转换器，核心库仅依赖 Python 标准库，其他功能通过可选依赖按需安装。v0.1.0 之后支持流式处理，不创建临时文件。基础转换不依赖 LLM，但可选用 LLM 增强图片描述与 OCR 功能。此外，项目提供 MCP 服务器，便于 AI 客户端直接调用。
解决什么问题 在 LLM 和 AI 应用爆发之前，文档转换主要服务于人类阅读。AI 时代带来了新需求：让机器能够“读懂”任意格式的文件。报告指出五大痛点：
格式碎片化 ：企业中文件格式多样（PDF、DOCX、XLSX、PPTX 等），每种格式内部结构不同，传统方案需为每种格式写专门解析器，维护成本高。LLM 无法直接处理二进制文件 ：LLM 输入是文本 token，接入 RAG 管道前必须有“预处理层”将文件转换为文本，转换质量直接决定下游检索效果。传统工具输出不适合 LLM ：textract 输出纯文本丢失结构，pdfplumber 输出 Python 对象需额外处理，这些工具提取的是“字符”而非“语义结构”。结构信息丢失严重 ：章节标题、表格、列表等结构对 LLM 理解文档至关重要，纯文本转换会丢失文档组织逻辑。图片和扫描件处理链路断裂 ：传统文本提取工具对嵌入图片和扫描件无能为力，需单独引入 OCR 引擎，且输出与文档文本“缝合”困难。
核心矛盾是：文档转换不再是“格式到格式”的问题，而是“二进制到语义”的问题。
工作方式 MarkItDown 采用可插拔的 Converter 架构，每种文件格式对应一个独立的 DocumentConverter（如 PdfConverter、DocxConverter、XlsxConverter 等），共享统一接口（输入文件流 → 输出 Markdown 文本）。整体工作流程为：输入文件 → 格式识别（扩展名 + MIME 类型）→ Converter 选择 → 文件流解析 → 结构提取 → Markdown 序列化 → 输出。
核心库只依赖 Python 标准库，PDF、Office、音频转录等功能通过可选依赖组（如 pip install markitdown[pdf]）按需安装。v0.1.0 之后改为基于文件流的处理，convert_stream() 接收二进制文件流，在内存中完成解析，不创建临时文件。
基础转换完全不需要 LLM，但可选接入 LLM 增强特定能力：用 GPT-4o 为图片生成描述、用 LLM Vision 做 OCR。项目还提供 MCP 服务器，让 Claude Desktop、VS Code Copilot 等 AI 客户端直接调用转换能力。
核心能力
支持 15+ 种文件格式，覆盖 PDF、Office、图片、音频、HTML、EPUB 等
输出结构化 Markdown，保留标题、列表、表格等结构信息
可插拔 Converter 架构，新增格式支持无需修改核心代码
核心库仅依赖 Python 标准库，功能按需安装
流式处理，零临时文件，适合容器化部署和管道操作
基础转换不依赖 LLM，可选 LLM 增强图片描述与 OCR
提供 MCP 服务器，AI 客户端可直接调用
插件系统支持第三方扩展，社区通过 #markitdown-plugin 标签共享插件
采用 MIT 开源协议
使用前需要了解
AI 整理 · 本地测试，未经人工复核；依据历史报告节选，不代表当前产品状态。
简体中文 · AI 译文 原文
AI 中文译文，非官方翻译；安装命令与技术细节请对照原文。
MarkItDown
PyPI（请在原文查看） PyPI - Downloads（请在原文查看）
[!IMPORTANT]
MarkItDown 以当前进程的权限执行 I/O 操作。与 open() 或 requests.get() 类似，它会访问进程本身可以访问的资源。在不受信任的环境中请对输入进行消毒，并调用满足用例所需的最小范围 convert_* 函数（例如 convert_stream() 或 convert_local()）。更多信息请参阅文档中的安全注意事项 部分。
MarkItDown 是一个轻量级 Python 工具，用于将各种文件转换为 Markdown，供 LLM 及相关文本分析管道使用。为此，它与 textract 最为相似，但更注重将重要的文档结构和内容保留为 Markdown（包括：标题、列表、表格、链接等）。虽然输出通常相当美观且对用户友好，但它旨在供文本分析工具使用——可能不是用于人工阅读的高保真文档转换的最佳选择。
MarkItDown 目前支持从以下格式转换：
PDF
PowerPoint
Word
Excel
图片（EXIF 元数据和 OCR）
音频（EXIF 元数据和语音转录）
HTML
基于文本的格式（CSV、JSON、XML）
ZIP 文件（遍历内容）
YouTube 链接
EPUB
……以及更多！
为什么选择 Markdown？
Markdown 非常接近纯文本，标记或格式极少，但仍然能够表示重要的文档结构。主流 LLM，如 OpenAI 的 GPT-4o，原生“说 ”Markdown，并且经常在未提示的情况下将 Markdown 融入其响应中。这表明它们已经接受了大量 Markdown 格式文本的训练，并且理解得很好。作为额外好处，Markdown 约定也具有很高的 token 效率。
先决条件
MarkItDown 需要 Python 3.10 或更高版本。建议使用虚拟环境以避免依赖冲突。
使用标准 Python 安装，您可以通过以下命令创建并激活虚拟环境：
python -m venv .venv
source .venv/bin/activate
如果使用 uv，您可以通过以下方式创建虚拟环境：
uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment
如果您使用 Anaconda，您可以通过以下方式创建虚拟环境：
conda create -n markitdown python=3.12
conda activate markitdown
安装
要安装 MarkItDown，请使用 pip：pip install 'markitdown[all]'。或者，您也可以从源码安装：
不适合高保真人类阅读转换 ：输出为机器消费的 Markdown，不是排版精美的文档。
PDF 表格质量有限 ：对复杂表格（合并单元格、嵌套表格、无边框表格）转换质量不如 Docling 和 Azure Document Intelligence。
不支持 LaTeX/数学公式 ：无法提取和保留学术论文中的数学公式。
LLM 增强依赖外部 API ：图片描述和 OCR 功能需调用 OpenAI 兼容 API，产生额外成本和延迟，离线环境或成本敏感场景受限。
扫描件 OCR 质量取决于 LLM ：对模糊、倾斜、手写扫描件效果可能不如专业 OCR 引擎。
相对年轻 ：2024 年 11 月开源，生产验证时间较短，API 在 v0.0.1 → v0.1.0 有 breaking changes。
不提取文档样式 ：字体、颜色、布局等样式信息不会保留。
音频转录依赖 Google Web Speech API ：国内网络环境可能受限。
大文件处理 ：流式处理避免内存溢出，但仍需注意 PDF 等格式解析的内存消耗。
LLM 成本 ：启用 LLM 增强后，每个图片/音频都会产生 API 调用费用。git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
用法
命令行 markitdown path-to-file.pdf > document.md
markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown
可选依赖 MarkItDown 具有用于激活各种文件格式的可选依赖。在本文档前面，我们使用 [all] 选项安装了所有可选依赖。但是，您也可以单独安装它们以进行更精细的控制。例如：
pip install 'markitdown[pdf, docx, pptx]'
将仅安装 PDF、DOCX 和 PPTX 文件的依赖。
[all] 安装所有可选依赖[pptx] 安装 PowerPoint 文件的依赖[docx] 安装 Word 文件的依赖[xlsx] 安装 Excel 文件的依赖[xls] 安装旧版 Excel 文件的依赖[pdf] 安装 PDF 文件的依赖[outlook] 安装 Outlook 邮件的依赖[az-doc-intel] 安装 Azure Document Intelligence 的依赖[az-content-understanding] 安装 Azure Content Understanding 的依赖[audio-transcription] 安装 wav 和 mp3 文件音频转录的依赖[youtube-transcription] 安装获取 YouTube 视频转录的依赖
插件 MarkItDown 还支持第三方插件。插件默认禁用。要列出已安装的插件：
markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf
要查找可用插件，请在 GitHub 上搜索标签 #markitdown-plugin。要开发插件，请参阅 packages/markitdown-sample-plugin。
markitdown-ocr 插件 markitdown-ocr 插件为 PDF、DOCX、PPTX 和 XLSX 转换器添加了 OCR 支持，使用 LLM Vision 从嵌入图像中提取文本——这与 MarkItDown 已用于图像描述的 llm_client / llm_model 模式相同。无需新的 ML 库或二进制依赖。
pip install markitdown-ocr
pip install openai # or any OpenAI-compatible client
传递与图像描述相同的 llm_client 和 llm_model：
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(
enable_plugins=True,
llm_client=OpenAI(),
llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.markdown)
如果未提供 llm_client，插件仍会加载，但 OCR 会被静默跳过，并使用标准内置转换器。
Azure Content Understanding 安装：pip install 'markitdown[az-content-understanding]'
何时使用 Content Understanding 当您需要超出内置或 Document Intelligence 转换器提供的能力时，Content Understanding 是理想选择：
音频和视频文件 — CU 是视频的唯一选项，也是音频的更高质量云选项。内置转换器不支持视频，仅提供基本的音频转录。结构化字段提取 — 预构建 或自定义构建 的分析器提取领域特定字段（发票金额、收据日期、合同条款），并序列化为 YAML front matter。内置和 Doc Intel 集成均不暴露字段。更高质量的文档提取 — 基于云的布局分析和 OCR，适用于扫描 PDF、复杂表格和多页文档。所有模态的单一 API — 一个 cu_endpoint 即可处理文档、图像、音频和视频，并自动路由分析器。 markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
端点也可以在环境中设置一次，因此调用者只需 --use-cu：
export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
markitdown path-to-file.pdf --use-cu
from markitdown import MarkItDown
# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf") # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4") # video → prebuilt-videoSearch
result = md.convert("call.wav") # audio → prebuilt-audioSearch
print(result.markdown)
md = MarkItDown(
cu_endpoint="<content_understanding_endpoint>",
cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
# VendorName: CONTOSO LTD.
# InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...
当设置 cu_analyzer_id 时，转换器会根据分析器的模态自动将其范围限定为兼容的文件类型。不兼容的类型（例如，文档分析器处理音频文件）会自动路由到默认的预构建分析器。
成本说明： 每次对 CU 路由格式调用 convert() 都是一次计费的 Azure API 调用。使用 cu_file_types 来限制哪些格式路由到 CU：
from markitdown.converters import ContentUnderstandingFileType
md = MarkItDown(
cu_endpoint="<content_understanding_endpoint>",
cu_file_types=[ContentUnderstandingFileType.PDF], # only PDFs use CU
)
关于 Azure 内容理解的更多信息可以在此处 找到。
Azure 文档智能 markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
端点也可以在环境中设置一次，这样调用者只需要 -d：
export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>"
markitdown path-to-file.pdf -o document.md -d
关于如何设置 Azure 文档智能资源的更多信息可以在此处 找到。
Python API from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.markdown)
from markitdown import MarkItDown
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.markdown)
要使用大型语言模型进行图像描述（目前仅适用于 pptx 和图像文件），请提供 llm_client 和 llm_model：
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.markdown)
Docker docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
贡献 在开始重要工作之前，请阅读要贡献的内容 ，其中描述了本仓库的范围内外内容。
当您提交拉取请求时，CLA 机器人会自动确定您是否需要提供
CLA，并适当装饰 PR（例如，状态检查、评论）。只需按照机器人
提供的说明操作即可。在使用我们 CLA 的所有仓库中，您只需执行一次此操作。
要贡献的内容 MarkItDown 是一个 Python 实用程序，用于将文件转换为 Markdown，以供 LLM 和相关的文本分析管道使用。本仓库旨在提供可整合到其他系统中的 Python 库——而不是构建在其之上的最终用户应用程序。
范围内
改进现有转换器的保真度（新格式的添加要谨慎——尤其是如果它们会引入新的依赖项。在大多数情况下，新格式可以通过第三方插件 更好地支持。）
错误修复、性能改进和安全修复
markitdown 命令行界面markitdown-mcp 包测试、文档和开发者工具
范围外 我们无法接受额外的应用程序、服务或服务器。这包括：
Web 服务器、REST 或 HTTP API，以及托管转换服务
Web 前端和基于浏览器的用户界面
桌面和移动应用程序（PyQt、PySide、Tkinter、Electron、Flutter 等）
像这样的项目确实很有用，我们更希望它们蓬勃发展，而不是被拒之门外。如果您有兴趣为 MarkItDown 提供 Web 服务、API 或图形应用程序，请将其作为依赖于 来自 PyPI 的 markitdown 的独立包或项目来维护。
在不更改此仓库的情况下扩展 MarkItDown MarkItDown 支持第三方插件，因此可以独立于此仓库发布和安装对新格式的支持：
markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf
参见 packages/markitdown-sample-plugin 开始使用，并将您的仓库标记为 #markitdown-plugin，以便其他人可以找到它。
如何贡献 您可以通过查看问题或帮助审查 PR 来提供帮助。我们还标记了一些问题为“开放贡献”和 PR 为“开放审查”，以帮助促进社区贡献。这些标签是建议；上述范围内的贡献都是受欢迎的。
运行测试和检查
导航到 MarkItDown 包：
cd packages/markitdown
在您的环境中安装 hatch 并运行测试：
pip install hatch # Other ways of installing hatch: https://hatch.pypa.io/dev/install/
hatch shell
hatch test
（备选）使用已安装所有依赖项的 Devcontainer：
# Reopen the project in Devcontainer and run:
hatch test
在提交 PR 之前运行 pre-commit 检查：pre-commit run --all-files
安全注意事项 MarkItDown 以当前进程的权限执行 I/O。像 open() 或 requests.get() 一样，它将访问进程本身可以访问的资源。
净化您的输入： 不要将不受信任的输入直接传递给 MarkItDown。如果输入的任何部分可能由不受信任的用户或系统控制，例如在托管或服务器端应用程序中，则必须在调用 MarkItDown 之前对其进行验证和限制。根据您的环境，这可能包括限制文件路径、限制 URI 方案和网络目标，以及阻止访问私有、环回、链路本地或元数据服务地址。
只调用您需要的转换方法： 优先选择最适合您用例的最窄转换 API。MarkItDown 的 convert() 方法有意设计为宽松的，可以处理本地文件、远程 URI 和字节流。如果您的应用程序只需要读取本地文件，请改为调用 convert_local()。如果您需要对 URI 获取进行更多控制，请自行调用 requests.get() 并将响应对象传递给 convert_response()。为了最大程度地控制，请打开要转换的输入的流并调用 convert_stream()。
商标 本项目可能包含项目、产品或服务的商标或徽标。授权使用 Microsoft 商标或徽标须遵守并遵循
Microsoft 的商标与品牌指南 。
在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。
任何对第三方商标或徽标的使用均受该第三方政策的约束。
09.08
