一、MarkItDown 是什么MarkItDown 是一个文档转换工具可以把多种格式转换成 Markdown特别适合下面这些场景把“原理图.pdf”“说明书.docx”等资料提取成文字和 Markdown方便阅读、检索、复制方便喂给 AI 大模型做知识库、总结、问答支持 PDF、Word、PPT、Excel、HTML、图片 OCR 等格式。适用环境WindowsPython 3安装完整版后可转换的格式包括类型扩展名PDF 文档.pdfWord 文档.docxPowerPoint.pptxExcel 表格.xlsx网页.html / .htm图片 OCR.png / .jpg 等其他CSV、JSON、XML、ZIP、EPUB 等二、最初的报错与根本原因很多人在安装时会遇到两个典型报错powershell无法将“pip”项识别为 cmdlet、函数、脚本文件或可运行程序的名称或者输入powershellmarkitdown --help提示找不到命令。根本原因通常有三个电脑没有安装 Python安装 Python 时没有勾选Add Python to PATHPython 和 pip 没有加入系统环境变量环境变量缺失导致 PowerShell / CMD 识别不到 pip 程序。MarkItDown 还没装上markitdown命令自然也不存在所以这两个报错本质上是同一个原因。解决思路统一使用python -m pip和python -m markitdown的写法可以绕过 PATH 问题无需手动改环境变量。三、第一步确认 Python 是否安装打开 PowerShell 或 CMD输入powershellpython --version如果不行再试powershellpy --version结果判断输出版本号例如Python 3.14.7说明 Python 已安装直接进入下一步提示“无法识别”说明电脑没有安装 Python需要先安装。安装 Python 的关键注意事项到 Python 官网下载安装包运行安装程序时安装界面第一屏务必勾选Add Python to PATH再点击Install Now安装完成后关闭并重新打开 PowerShell / CMD再执行上面的版本检查命令。四、第二步安装 MarkItDown在 PowerShell 或 CMD 中执行下面这条命令推荐安装完整版支持 PDF、Word、图片 OCR 等全部格式powershellpython -m pip install markitdown[all]如果只需要基础功能powershellpython -m pip install markitdown为什么不直接用pip install因为本机 pip 不在系统 PATH 中直接敲pip会报“命令找不到”。python -m pip是官方推荐的兼容写法显式调用当前 Python 对应的 pip稳定可靠。如果python命令不可用但py启动器可用可以改用powershellpy -m pip install markitdown[all]五、第三步验证安装执行powershellpython -m markitdown --help能正常打印帮助信息说明安装成功。注意即使安装成功直接敲powershellmarkitdown --help仍可能报“找不到命令”这是 Python 的 Scripts 目录没有加入 PATH 导致的。统一用powershellpython -m markitdown调用即可不影响使用。六、单文件转换核心用法命令格式powershellpython -m markitdown 源文件.pdf -o 输出文件.md实例转换“原理图.pdf”powershellpython -m markitdown 原理图.pdf -o 原理图.md操作步骤打开 PowerShell 或 CMD先切换到文件所在文件夹这一步非常重要否则会提示找不到文件。例如文件放在textE:\Project\COP8CCR9\自制烧录工具PowerShell 下切换powershellcd E:\Project\COP8CCR9\自制烧录工具CMD 下跨盘符切换需加/dcmdcd /d E:\Project\COP8CCR9\自制烧录工具执行转换命令转换完成后同一文件夹下会生成原理图.md。文件名两侧加上英文半角双引号用于处理中文文件名和带空格的文件名建议始终带上。七、两种备选写法1. 只在终端预览内容不生成文件powershellpython -m markitdown 原理图.pdf2. 管道重定向写法PowerShell 推荐指定 UTF-8 编码避免中文乱码powershellpython -m markitdown 原理图.pdf | Out-File 原理图.md -Encoding utf8CMD 下的管道写法cmdpython -m markitdown 原理图.pdf 原理图.md3. 扫描版 / 图片型 PDF需要 OCR如果 PDF 是扫描件、截图合成的里面的文字无法用鼠标选中复制需要启用 OCR 插件识别文字powershellpython -m markitdown --use-plugins 原理图.pdf -o 原理图.md八、重要为什么没有生成 md 文件执行下面这条命令后目录里没有出现 md 文件powershellpython -m markitdown 原理图.pdf原因不带-o参数时MarkItDown 只会把转换后的 Markdown 内容打印到终端屏幕上不会写入文件。屏幕上滚动显示的那些文本其实就是提取出来的 Markdown 内容只是没有保存。解决方法必须加上-o输出文件名powershellpython -m markitdown 原理图.pdf -o 原理图.md执行后当前目录就会生成原理图.md。九、批量转换脚本版本 1BAT 批处理双击即可运行新建一个文本文件粘贴以下内容保存为批量转换.bat保存时“保存类型”选“所有文件”编码选 ANSI / GBK把它放到 PDF 所在文件夹双击运行即可把当前文件夹所有 PDF 转成同名 md。batecho off for %%f in (*.pdf) do ( python -m markitdown %%f -o %%~nf.md ) echo 全部转换完成 pause版本 2PowerShell 脚本新建文本文件粘贴以下内容保存为批量转换PDF转MD.ps1放到 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 窗口执行powershellSet-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass然后再运行脚本。该设置只对当前窗口生效关闭后自动恢复。十、支持的文件类型安装markitdown[all]完整版后可直接转换类型扩展名PDF 文档.pdfWord 文档.docxPowerPoint.pptxExcel 表格.xlsx网页.html / .htm图片 OCR 识别文字.png / .jpg 等其他CSV、JSON、XML、ZIP、EPUB 等转换其他格式的命令完全一样替换文件名即可例如powershellpython -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 问题找到 Python 安装目录例如textC:\Python311\以及其中的 Scripts 文件夹textC:\Python311\Scripts\把这两个路径添加到系统环境变量 → Path关闭所有 PowerShell / CMD 窗口重新打开此后即可直接使用powershellpip 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. 扫描版 PDFOCR 识别 python -m markitdown --use-plugins 原理图.pdf -o 原理图.md # 7. 转换 Word 等其他格式 python -m markitdown 说明书.docx -o 说明书.md十三、总结本教程根据实际安装排错过程整理核心就两句话安装和调用都加上python -m前缀绕开环境变量问题想生成文件必须带-o参数。如果你只是想预览内容可以不加-o如果你要保存成 Markdown 文件一定要写powershellpython -m markitdown 源文件.pdf -o 输出文件.md这样基本就能在 Windows Python 3 环境下顺利使用 MarkItDown 了。