《Windows 下 MarkItDown 安装与使用教程：PDF/Word/PPT/Excel/图片 OCR 一键转 Markdown》

一、MarkItDown 是什么？

MarkItDown 是一个文档转换工具，可以把多种格式转换成 Markdown，特别适合下面这些场景：

• 把“原理图.pdf”“说明书.docx”等资料提取成文字和 Markdown；

• 方便阅读、检索、复制；

• 方便喂给 AI 大模型做知识库、总结、问答；

• 支持 PDF、Word、PPT、Excel、HTML、图片 OCR 等格式。

适用环境：

• Windows

• Python 3

安装完整版后，可转换的格式包括：

类型	扩展名
PDF 文档	.pdf
Word 文档	.docx
PowerPoint	.pptx
Excel 表格	.xlsx
网页	.html / .htm
图片 OCR	.png / .jpg 等
其他	CSV、JSON、XML、ZIP、EPUB 等

---

二、最初的报错与根本原因

很多人在安装时会遇到两个典型报错：

powershell

无法将“pip”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

或者输入：

powershell

markitdown --help

提示找不到命令。

根本原因通常有三个：

1. 电脑没有安装 Python；

2. 安装 Python 时没有勾选Add Python to PATH，Python 和 pip 没有加入系统环境变量；

3. 环境变量缺失，导致 PowerShell / CMD 识别不到 pip 程序。

MarkItDown 还没装上，markitdown命令自然也不存在，所以这两个报错本质上是同一个原因。

解决思路：

统一使用python -m pip和python -m markitdown的写法，可以绕过 PATH 问题，无需手动改环境变量。

---

三、第一步：确认 Python 是否安装

打开 PowerShell 或 CMD，输入：

powershell

python --version

如果不行，再试：

powershell

py --version

结果判断：

• 输出版本号，例如Python 3.14.7：说明 Python 已安装，直接进入下一步；

• 提示“无法识别”：说明电脑没有安装 Python，需要先安装。

安装 Python 的关键注意事项：

1. 到 Python 官网下载安装包；

2. 运行安装程序时，安装界面第一屏务必勾选Add Python to PATH；

3. 再点击Install Now；

4. 安装完成后，关闭并重新打开 PowerShell / CMD，再执行上面的版本检查命令。

---

四、第二步：安装 MarkItDown

在 PowerShell 或 CMD 中执行下面这条命令，推荐安装完整版，支持 PDF、Word、图片 OCR 等全部格式：

powershell

python -m pip install "markitdown[all]"

如果只需要基础功能：

powershell

python -m pip install markitdown

为什么不直接用pip install？

因为本机 pip 不在系统 PATH 中，直接敲pip会报“命令找不到”。python -m pip是官方推荐的兼容写法，显式调用当前 Python 对应的 pip，稳定可靠。

如果python命令不可用，但py启动器可用，可以改用：

powershell

py -m pip install "markitdown[all]"

---

五、第三步：验证安装

执行：

powershell

python -m markitdown --help

能正常打印帮助信息，说明安装成功。

注意：

即使安装成功，直接敲：

powershell

markitdown --help

仍可能报“找不到命令”，这是 Python 的 Scripts 目录没有加入 PATH 导致的。

统一用：

powershell

python -m markitdown

调用即可，不影响使用。

---

六、单文件转换（核心用法）

命令格式：

powershell

python -m markitdown "源文件.pdf" -o "输出文件.md"

实例：转换“原理图.pdf”：

powershell

python -m markitdown "原理图.pdf" -o "原理图.md"

操作步骤：

1. 打开 PowerShell 或 CMD；

2. 先切换到文件所在文件夹，这一步非常重要，否则会提示找不到文件。

例如文件放在：

text

E:\Project\COP8CCR9\自制烧录工具

PowerShell 下切换：

powershell

cd E:\Project\COP8CCR9\自制烧录工具

CMD 下跨盘符切换需加/d：

cmd

cd /d E:\Project\COP8CCR9\自制烧录工具

1. 执行转换命令；

2. 转换完成后，同一文件夹下会生成原理图.md。

文件名两侧加上英文半角双引号，用于处理中文文件名和带空格的文件名，建议始终带上。

---

七、两种备选写法

1. 只在终端预览内容，不生成文件

powershell

python -m markitdown "原理图.pdf"

2. 管道重定向写法

PowerShell 推荐指定 UTF-8 编码，避免中文乱码：

powershell

python -m markitdown "原理图.pdf" | Out-File "原理图.md" -Encoding utf8

CMD 下的管道写法：

cmd

python -m markitdown "原理图.pdf" > "原理图.md"

3. 扫描版 / 图片型 PDF（需要 OCR）

如果 PDF 是扫描件、截图合成的，里面的文字无法用鼠标选中复制，需要启用 OCR 插件识别文字：

powershell

python -m markitdown --use-plugins "原理图.pdf" -o "原理图.md"

---

八、重要：为什么没有生成 md 文件？

执行下面这条命令后，目录里没有出现 md 文件：

powershell

python -m markitdown "原理图.pdf"

原因：

不带-o参数时，MarkItDown 只会把转换后的 Markdown 内容打印到终端屏幕上，不会写入文件。

屏幕上滚动显示的那些文本，其实就是提取出来的 Markdown 内容，只是没有保存。

解决方法：

必须加上-o输出文件名：

powershell

python -m markitdown "原理图.pdf" -o "原理图.md"

执行后，当前目录就会生成原理图.md。

---

九、批量转换脚本

版本 1：BAT 批处理（双击即可运行）

1. 新建一个文本文件；

2. 粘贴以下内容；

3. 保存为批量转换.bat，保存时“保存类型”选“所有文件”，编码选 ANSI / GBK；

4. 把它放到 PDF 所在文件夹，双击运行，即可把当前文件夹所有 PDF 转成同名 md。

bat

@echo off for %%f in (*.pdf) do ( python -m markitdown "%%f" -o "%%~nf.md" ) echo 全部转换完成 pause

版本 2：PowerShell 脚本

1. 新建文本文件，粘贴以下内容；

2. 保存为批量转换PDF转MD.ps1；

3. 放到 PDF 所在文件夹，右键 → 使用 PowerShell 运行。

powershell

# 批量将当前目录所有 pdf 转成同名 md Get-ChildItem -Filter *.pdf | ForEach-Object { $inputFile = $_.FullName $outputFile = $_.BaseName + ".md" Write-Host "正在转换：$($_.Name)" python -m markitdown "$inputFile" -o "$outputFile" } Write-Host "全部转换完成！" pause

若提示脚本执行策略限制，可先在当前 PowerShell 窗口执行：

powershell

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

然后再运行脚本。该设置只对当前窗口生效，关闭后自动恢复。

---

十、支持的文件类型

安装markitdown[all]完整版后，可直接转换：

类型	扩展名
PDF 文档	.pdf
Word 文档	.docx
PowerPoint	.pptx
Excel 表格	.xlsx
网页	.html / .htm
图片 OCR 识别文字	.png / .jpg 等
其他	CSV、JSON、XML、ZIP、EPUB 等

转换其他格式的命令完全一样，替换文件名即可，例如：

powershell

python -m markitdown "说明书.docx" -o "说明书.md"

---

十一、常见报错与排查

报错 / 现象	原因	解决方法
无法将“pip”项识别为 cmdlet...	pip 不在 PATH	不要直接用 pip，改用python -m pip install ...
无法将“python”项识别...	未装 Python 或未加入 PATH	安装 Python 时勾选 Add Python to PATH，重装后重启终端；或改用py命令
无法将“markitdown”项识别...	Scripts 目录不在 PATH	用python -m markitdown调用，不要直接敲markitdown
执行后没有生成 md 文件	缺少-o参数	加上-o参数并指定输出名，如-o "输出文件名.md"
提示找不到文件	当前目录不对	先用cd切换到文件所在文件夹，再执行转换
中文文件名报错	特殊字符 / 编码问题	文件名用英文双引号包裹；尽量避免特殊符号
扫描版 PDF 转出来是空的或乱码	图片型 PDF，需要 OCR	加--use-plugins参数
中文 md 打开乱码	输出编码不是 UTF-8	用 PowerShell 管道写法并指定-Encoding utf8

可选：手动修复环境变量，彻底根治 PATH 问题

1. 找到 Python 安装目录，例如：

text

C:\Python311\

以及其中的 Scripts 文件夹：

text

C:\Python311\Scripts\

1. 把这两个路径添加到系统环境变量 → Path；

2. 关闭所有 PowerShell / CMD 窗口，重新打开；

3. 此后即可直接使用：

powershell

pip install ... markitdown ...

---

十二、命令速查表

powershell

# 1. 检查 Python 版本 python --version # 2. 安装完整版 markitdown python -m pip install "markitdown[all]" # 3. 查看帮助 python -m markitdown --help # 4. 转换单个文件（生成 md） python -m markitdown "原理图.pdf" -o "原理图.md" # 5. 只在屏幕预览，不生成文件 python -m markitdown "原理图.pdf" # 6. 扫描版 PDF（OCR 识别） python -m markitdown --use-plugins "原理图.pdf" -o "原理图.md" # 7. 转换 Word 等其他格式 python -m markitdown "说明书.docx" -o "说明书.md"

---

十三、总结

本教程根据实际安装排错过程整理，核心就两句话：

1. 安装和调用都加上python -m前缀，绕开环境变量问题；

2. 想生成文件必须带-o参数。

如果你只是想预览内容，可以不加-o；
如果你要保存成 Markdown 文件，一定要写：

powershell

python -m markitdown "源文件.pdf" -o "输出文件.md"

这样基本就能在 Windows + Python 3 环境下顺利使用 MarkItDown 了。