TL;DR#

markitdown 是微软开源的本地文档转换工具，支持 Word (.docx/.doc)、PowerPoint (.pptx)、Excel (.xlsx/.xls)、PDF、Outlook (.msg)、音频、YouTube 视频 等多种格式转为 Markdown。

全部计算在本地完成，不依赖任何外部 API 或 OpenAPI 服务。

为什么需要这个工具#

在日常工作中，我们经常遇到需要将各种文档格式转为 Markdown 的场景：

  • 知识库文档从 Word 迁移到 Markdown 格式
  • PPT 演示文稿内容提取
  • PDF 报告转为可搜索的文本
  • Excel 数据表格转为 Markdown 表格

在我的使用里，markitdown 目前比较好地覆盖了“格式转换”和“离线可用”这两个需求。

前置条件#

markitdown 要求 Python 3.10+。macOS 自带的 Python 通常版本较低，需要通过 Homebrew 安装新版本。

1. 确认 Homebrew 可用# 

brew --version
# Homebrew 5.x

2. 安装 Python 3.12# 

brew install python@3.12

安装路径：/opt/homebrew/bin/python3.12（Apple Silicon Mac）。

3. 创建虚拟环境#

在项目目录下创建虚拟环境（我一般放在项目内，避免全局污染）：

/opt/homebrew/bin/python3.12 -m venv .venv

4. 安装 markitdown#

markitdown 的依赖按文件格式分组，我这里直接使用 [all] 安装所有格式支持：

.venv/bin/pip install 'markitdown[all]'

如果只关心部分格式，也可以按需安装：

# 只装 PDF + Word + PPT
.venv/bin/pip install 'markitdown[pdf, docx, pptx]'

5. 全局可用（可选）#

将虚拟环境的 bin 目录加入 ~/.zshrc：

echo 'export PATH="/path/to/project/.venv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

之后在任何目录都可以直接运行 markitdown。

安装验证# 

markitdown --version
# markitdown 0.1.6b2

基本用法#

转换文件并输出到文件# 

markitdown report.docx -o report.md

转换并输出到 stdout# 

markitdown presentation.pptx

重定向到文件# 

markitdown data.xlsx > data.md

从 stdin 读取（需要指定扩展名）# 

cat document.docx | markitdown -x docx > document.md

指定输出字符集# 

markitdown legacy.docx -o output.md -e UTF-8

支持的格式一览#

格式 扩展名 底层库
Word 文档 .docx, .doc mammoth, lxml
PowerPoint .pptx python-pptx
Excel .xlsx, .xls openpyxl, xlrd
PDF .pdf pdfplumber, pdfminer
Outlook .msg olefile
图片 .png, .jpg, … 自动检测
音频 .mp3, .wav, … pydub
YouTube URL youtube-transcript-api
纯文本 .txt, .log, … -
代码文件 .py, .js, … -

底层通过 magika 自动检测文件类型，不需要手动指定扩展名。

注意事项#

音频转写需要 ffmpeg#

安装时若出现 RuntimeWarning: Couldn't find ffmpeg 警告：

brew install ffmpeg

这是音频格式转写（如语音转文字）的依赖。

Azure Document Intelligence（可选）#

使用 --use-docintel 参数可连接 Azure 云服务进行高精度文档解析，但这不是必需的，很多普通场景并不需要。

# 需要 Azure 账户时才需要
markitdown report.pdf --use-docintel --endpoint https://your-resource.cognitiveservices.azure.com/

不依赖 MCP#

markitdown 本身是一个 CLI 工具，不需要 MCP（Model Context Protocol）服务，也不依赖任何 OpenAPI 服务。所有转换都在本地完成。

表格较多的 PDF：markitdown 的局限与替代方案#

这是实际使用中最容易踩到的坑。

问题：表格结构会丢失#

markitdown 的 PDF 底层依赖 pdfplumber / pdfminer，它们只能提取字符及其位置信息，对表格的行列结构支持有限。遇到含表格的 PDF 时，输出会散成一团文本：

Task Guideline
Task Learning Outcome Duration
Java (OOP) Understand core object-oriented programming principles and write
clean, modular Java code.
Spring Build and configure RESTful APIs, manage dependencies, secure
Boot applications, and integrate with other systems.
...

| 列1 | 列2 | 的 Markdown 表格结构会直接丢失。对于培训手册、技术文档、报表等表格较多的 PDF，这个结果往往不太适合直接拿来用。

替代方案：换用 marker-pdf#

marker-pdf 是一个基于深度学习的 PDF 转 Markdown 工具。它使用专门的 Table Recognition 模型来识别和还原表格行列关系，按我目前处理表格 PDF 的体验，效果通常会更好一些。

安装# 

.venv/bin/pip install marker-pdf

首次运行会自动下载 4 个 PyTorch 模型（总共约 3.5GB）：

模型 大小 用途
layout ~1.35 GB 识别页面元素（标题/段落/表格/图片）
text_recognition ~1.34 GB 文字识别和行检测
table_recognition ~201 MB 识别表格行列结构
ocr_error_detection ~258 MB 检测是否需要 OCR

模型缓存在 ~/Library/Caches/datalab/models/，后续调用直接读取。

使用# 

# 转换单个文件
marker_single input.pdf --output_dir . --output_format markdown

# 批量转换
marker ./input_folder --output_dir ./output_folder --workers 4

效果对比#

同样是那份表格文档，marker-pdf 的输出：

| Task | Learning Outcome | Duration |
|------|------------------|----------|
| Java (OOP) | Understand core object-oriented programming principles... | |
| Spring Boot | Build and configure RESTful APIs... | |
| MySQL | Design and manage relational databases... | |

表格结构完整保留。

维度 markitdown marker-pdf
纯文本 PDF ✅ 很好 ✅ 很好
表格 PDF ❌ 结构丢失 ✅ 准确还原
扫描件 ❌ 较差 ✅ OCR 支持
安装复杂度 简单 需 PyTorch + 3.5GB 模型
转换速度 快（秒级） 中等（分钟级）

如何选择#

场景 更合适的工具
纯文本 PDF、快速提取 markitdown
含表格的技术文档 marker-pdf
扫描版 / 图片型 PDF marker-pdf（--force_ocr）
大批量、对质量要求不高 markitdown
两者都装了 先 markitdown，表格散了再换 marker-pdf

两者互不冲突，可以共存。对我来说，“markitdown 先试、表格不行再切 marker-pdf”会更实用。

总结#

markitdown 的安装核心就三步：

  1. brew install python@3.12 — 满足 Python 3.10+ 要求
  2. .venv/bin/pip install 'markitdown[all]' — 安装所有格式支持
  3. 随时使用 markitdown <file> -o <output.md>

离线可用、外部依赖少、格式支持也比较全。如果 PDF 中包含大量表格，我更倾向直接切到 marker-pdf。