MinerU 新手完整配置教程：Windows 下将 PDF 转为带图片的 Markdown

title: MinerU 新手完整配置教程：Windows 下将 PDF 转为带图片的 Markdown
作者: 肖恭伟
tags:

• MinerU
• PDF
• Markdown
• OCR
• Windows
• 文献阅读

MinerU 新手完整配置教程：Windows 下将 PDF 转为带图片的 Markdown

本文记录一次完整的 MinerU 配置、运行、排错和复盘过程，面向第一次接触命令行工具的 Windows 用户。

目标是把论文 PDF 转换为可在 Cursor、VS Code、Typora 或 Obsidian 中阅读的 Markdown，并保留公式、表格和图片资源。

一、先看正确步骤

新手建议严格按下面的顺序操作：

1. 安装 64 位 Python 3.10～3.13，并确认python和pip可用。
2. 建立一个不含空格的工作目录，例如D:\MinerU。
3. 创建并激活 Python 虚拟环境。
4. 安装 MinerU，并确认版本。
5. 下载模型文件。
6. 准备输入 PDF，首次测试尽量使用英文或简单中文 PDF。
7. 使用明确的后端和输出目录运行转换。
8. 检查输出目录中的 Markdown、images图片目录和 JSON 文件。
9. 用支持 Markdown 预览的编辑器打开 Markdown，而不是直接双击纯文本文件。
10. 若图片缺失，先检查相对路径和输出目录，再判断是否需要重新转换。

整个流程可以概括为：

安装 Python → 创建虚拟环境 → 安装 MinerU → 下载模型 → 转换 PDF → 检查 images → Markdown 预览

二、MinerU 是什么

MinerU 是一个文档解析工具，可以将 PDF、图片、Word、PPT 和 Excel 等文件转换为结构化结果。对科研论文而言，它通常可以输出：

• Markdown 文本；
• 公式；
• HTML 表格；
• 从 PDF 中提取的图片；
• 中间 JSON 或内容列表；
• 带版面识别信息的 PDF。

需要注意：Markdown 文件只是文本文件，图片并不一定嵌入其中。Markdown 中的图片通常通过相对路径引用，因此图片文件必须和 Markdown 一起保留。

三、准备 Windows 环境

3.1 安装 Python

建议使用 64 位 Python 3.10、3.11、3.12 或 3.13。当前 MinerU 3.4.4 的 Python 要求为>=3.10,<3.14。

安装 Python 时建议勾选：

• Add Python.exe to PATH；
• pip；
• venv。

安装完成后，在 PowerShell 中执行：

python--version pip--version

如果系统中有多个 Python，也可以使用：

py--version py-0p

3.2 建立工作目录

建议把程序、输入文件和输出文件分开：

D:\MinerU\ ├─ .venv-mineru\ 虚拟环境 ├─ input\ 待转换 PDF └─ output\ 转换结果

在 PowerShell 中执行：

New-Item-ItemType Directory-Force-Path'D:\MinerU\input','D:\MinerU\output'|Out-NullSet-Location'D:\MinerU'

路径包含中文或空格时，必须使用引号。例如：

Set-Location'D:\我的论文\MinerU'

四、创建并激活虚拟环境

在D:\MinerU目录中执行：

python-m venv'.venv-mineru'.\.venv-mineru\Scripts\Activate.ps1

激活成功后，命令行前面通常会出现：

(.venv-mineru)

如果 PowerShell 提示禁止执行脚本，可以只为当前用户放开本地脚本权限：

Set-ExecutionPolicy-Scope CurrentUser RemoteSigned

然后重新激活：

.\.venv-mineru\Scripts\Activate.ps1

验证当前 Python 是否来自虚拟环境：

python-c"import sys; print(sys.executable)"

输出路径应指向：

D:\MinerU\.venv-mineru\Scripts\python.exe

五、安装 MinerU

先升级基础安装工具：

python-m pip install--upgrade pip setuptools wheel

安装 MinerU：

python-m pip install-U mineru

确认版本：

python-c"import importlib.metadata as m; print(m.version('mineru'))"

也可以确认命令行入口是否存在：

python-m mineru.cli.client--help

本文实际核验的版本是：

MinerU 3.4.4 Python 3.10.0

六、下载模型文件

MinerU 的部分后端需要本地模型。推荐使用模型下载命令：

python-m mineru.cli.models_download--help

下载通用 Pipeline 模型：

python-m mineru.cli.models_download-s modelscope-m pipeline

如果网络可以访问 Hugging Face，也可以使用：

python-m mineru.cli.models_download-s huggingface-m pipeline

如果计划使用 VLM 或混合高精度后端，可以下载全部模型：

python-m mineru.cli.models_download-s modelscope-m all

模型下载可能耗时较长，且需要较大的磁盘空间。下载过程中不要关闭 PowerShell。首次运行前，建议确认模型缓存已经生成。

七、准备待转换 PDF

将 PDF 放入输入目录。例如：

D:\MinerU\input\论文.pdf

检查文件是否存在：

Test-Path-LiteralPath'D:\MinerU\input\论文.pdf'Get-Item-LiteralPath'D:\MinerU\input\论文.pdf'|Select-ObjectFullName,Length

文件名包含中文时没有问题，但在 PowerShell 中建议始终使用-LiteralPath和引号，避免特殊字符被解释。

八、执行 PDF 转 Markdown

8.1 推荐的 Pipeline 后端

Pipeline 后端适合先完成稳定的 PDF 文本、公式、表格和图片解析：

python-m mineru.cli.client `-p'D:\MinerU\input\论文.pdf'`-o'D:\MinerU\output'`-b pipeline `-m auto `-l ch `-f true `-t true

PowerShell 使用反引号`换行。如果担心复制时丢失反引号，也可以写成一行：

python-m mineru.cli.client-p'D:\MinerU\input\论文.pdf'-o'D:\MinerU\output'-b pipeline-m auto-l ch-f true-t true

参数含义：

8.2 高精度混合后端

MinerU 3.4.4 还提供hybrid-engine。它更适合需要更高图表理解能力的场景，但本地计算资源和模型要求更高：

python-m mineru.cli.client `-p'D:\MinerU\input\论文.pdf'`-o'D:\MinerU\output'`-b hybrid-engine `--effort high `-l ch `-f true `-t true `--image-analysis true

--effort medium速度更快，但混合后端在 medium 模式下可能关闭图像或图表分析；需要图表分析时使用--effort high，但耗时会增加。

8.3 只转换指定页

排查问题时，不要一开始就转换几十页。可以先测试前 2 页：

python-m mineru.cli.client `-p'D:\MinerU\input\论文.pdf'`-o'D:\MinerU\output-test'`-b pipeline `-m auto `-l ch `-s 0 `-e 1

注意：-s和-e使用从0开始的页码。

九、检查输出结果

转换结束后，先不要急着打开 Markdown。先检查输出目录：

Get-ChildItem-LiteralPath'D:\MinerU\output'-Recurse-File|Select-ObjectFullName,Length,LastWriteTime

正常情况下，应当重点寻找：

*.md images\ *.json *_layout.pdf

典型结构类似：

D:\MinerU\output\论文\ ├─ auto\ │ ├─ 论文.md │ ├─ images\ │ │ ├─ image-1.jpg │ │ └─ image-2.jpg │ ├─ *.json │ └─ *_layout.pdf

检查图片数量：

$md=Get-ChildItem-LiteralPath'D:\MinerU\output'-Recurse-Filter'*.md'|Select-Object-First 1$md.FullName$images=Join-Path$md.DirectoryName'images'Write-Output('images exists: '+(Test-Path-LiteralPath$images))if(Test-Path-LiteralPath$images){(Get-ChildItem-LiteralPath$images-File).Count}

检查 Markdown 中的图片引用：

Select-String-LiteralPath$md.FullName-Pattern'!\[.*\]\('

逐个验证图片引用是否存在：

$mdText=Get-Content-LiteralPath$md.FullName-Raw-Encoding UTF8[regex]::Matches($mdText,'!\[[^]]*\]\(([^)]+)\)')|ForEach-Object{$relative=$_.Groups[1].Value$absolute=Join-Path$md.DirectoryName$relative[pscustomobject]@{Reference =$relativeExists =Test-Path-LiteralPath$absolutePath =$absolute}}

如果Exists为False，说明 Markdown 里的图片引用失效，不能仅靠更换阅读器解决。

十、正确打开带图片的 Markdown

10.1 Cursor 或 VS Code

1. 用 Cursor 或 VS Code 打开 Markdown 文件。
2. 按Ctrl+Shift+V打开 Markdown 预览。
3. 或按Ctrl+K，松开后再按V，在右侧打开预览。
4. Markdown 文件和images文件夹必须保持原有相对位置。

10.2 Typora

直接用 Typora 打开.md文件即可。图片文件夹不能移动或删除。

10.3 Obsidian

将 Markdown 文件和images文件夹放在同一个 Vault 内，并保持 Markdown 中的相对路径有效。若图片是 Markdown 标准路径，Obsidian 通常可以直接预览。

10.4 浏览器

浏览器直接打开 Markdown 文件通常只会显示源文本，不会自动按 Markdown 渲染。应使用支持 Markdown 的编辑器，或先通过 Markdown 插件/静态站点生成 HTML。

十一、为什么图片有时显示不出来

Markdown 中常见的图片引用是：

![](images/06b7e3b5753ec39beb4b89ccf8d6a1cbc2174adb8c9389bed6dc29dd7a843127.jpg)

这表示图片位于当前 Markdown 文件所在目录下的images子目录中。下面的文件结构才是正确的：

论文.md images\ └─ 06b7e3b5753ec39beb4b89ccf8d6a1cbc2174adb8c9389bed6dc29dd7a843127.jpg

以下情况都会导致图片不显示：

• 只有.md文件，没有images文件夹；
• 图片文件名被修改；
• Markdown 被移动到其他目录，但images没有一起移动；
• 相对路径层级不正确；
• 图片实际生成在另一个输出目录；
• 使用了浏览器或纯文本编辑器，而不是 Markdown 预览；
• PDF 本身是扫描图片，使用了不合适的解析模式；
• 转换过程没有正常结束。

十二、图片缺失时的处理方法

方法一：重新确认输出目录

Get-ChildItem-LiteralPath'D:\MinerU\output'-Recurse-Directory|Where-ObjectName-eq'images'

如果能找到images，把整个结果目录一起移动，不要只移动 Markdown。

方法二：重新转换并保留完整结果

建议删除或改名旧的测试输出目录，然后重新执行转换：

$input='D:\MinerU\input\论文.pdf'$output='D:\MinerU\output\论文-new'python-m mineru.cli.client-p$input-o$output-b pipeline-m auto-l ch-f true-t true

不要直接覆盖多个版本的输出，否则容易把 Markdown 和图片目录混在一起。

方法三：使用版面 PDF 辅助检查

如果输出中有*_layout.pdf，可以打开它检查 MinerU 对页面、文本块、表格和图片的识别结果。版面 PDF 主要用于核验版面，不等于 Markdown 图片资源本身。

十三、常见问题

13.1python不是命令

重新安装 Python 并勾选 PATH，或者使用 Python 安装器中的完整路径。也可以尝试：

py-3.10--version

13.2 PowerShell 禁止运行激活脚本

执行：

Set-ExecutionPolicy-Scope CurrentUser RemoteSigned

然后重新激活虚拟环境。

13.3 命令执行很久没有结束

首次运行可能需要加载模型。先确认：

• 是否正在下载模型；
• 磁盘空间是否充足；
• 内存是否足够；
• 输入 PDF 是否过大；
• 是否误用了需要更高算力的hybrid-engine。

新手排查时，优先使用pipeline，并用-s 0 -e 1只转换两页。

13.4 PDF 是扫描件，文字识别不完整

使用 OCR 模式：

python-m mineru.cli.client-p'D:\MinerU\input\扫描论文.pdf'-o'D:\MinerU\output\扫描论文'-b pipeline-m ocr-l ch

扫描件的公式、表格和图片识别效果取决于原始分辨率和版面复杂度，转换后必须人工核对。

13.5 公式或表格不准确

可以尝试开启公式和表格解析：

-f true-t true

但任何 OCR 或版面解析工具都不能保证科研论文公式 100% 正确。重要公式应回看原始 PDF。

13.6 需要读取图表内容怎么办

首先确认图片文件真实存在。若 Markdown 只有图片链接而没有图片资源，不能依据 Markdown 文件本身读取图像内容。此时应：

1. 找到原始 PDF；
2. 打开对应页或从 PDF 渲染页面；
3. 结合图注、正文上下文和图像本身进行总结；
4. 不要把 OCR 提取的图注当成图像识别结果。

十四、适合批量转换的 PowerShell 模板

下面的模板可批量处理输入目录中的 PDF：

$python='D:\MinerU\.venv-mineru\Scripts\python.exe'$inputDir='D:\MinerU\input'$outputDir='D:\MinerU\output'Get-ChildItem-LiteralPath$inputDir-Filter'*.pdf'-File|ForEach-Object{$pdf=$_.FullNameWrite-Host"正在转换：$pdf"&$python-m mineru.cli.client `-p$pdf`-o$outputDir`-b pipeline `-m auto `-l ch `-f true `-t true}

批量处理时，每次转换后都应检查输出目录，尤其是 Markdown 和images是否一一对应。

十五、推荐的科研文献工作流

原始 PDF ↓ MinerU 转换 ↓ 检查 Markdown、公式、表格和 images ↓ 用 Obsidian/Cursor/Typora 阅读 ↓ 回看原始 PDF 核验关键公式和图表 ↓ 提炼摘要、方法、数据、结论和可复现实验信息

对于论文图表，建议同时保留：

• 原始 PDF；
• MinerU Markdown；
• images图片目录；
• JSON 或中间结果；
• 人工修订后的笔记。

这样可以在 Markdown 解析不完整时回溯原始材料。

十六、本次配置的实际环境记录

本次环境中曾经使用过以下路径：

旧工作区：D:\AIAgent\findMySelf 当前 MinerU 环境：D:\AIAgent_obsidian\04-自动化系统\MinerU 虚拟环境：D:\AIAgent_obsidian\04-自动化系统\MinerU\.venv-mineru 输入示例：D:\MinerUInput 输出示例：D:\MinerUOut 结果示例：D:\MinerUResult

由于 Windows 系统中的目录可能被迁移、重命名或同步，教程中的路径只是示例。重新配置时，应先用Test-Path验证路径，再执行命令。

十七、经验与教训

17.1 正确认识 Markdown 与图片的关系

Markdown 通常只保存图片链接，不保存图片本体。看到：

![](images/example.jpg)

并不代表example.jpg一定存在。必须同时确认：

Markdown 文件所在目录\images\example.jpg

这也是本次打开论文 Markdown 时图片不显示的直接原因：文档中的图片引用存在，但对应的images资源目录没有出现在实际输出目录中。

17.2 输出目录必须整体保留

不要只复制.md文件。应复制整个论文结果目录。最少要一起保留 Markdown 和images；需要后续排错时，还应保留 JSON、版面 PDF 和原始 PDF。

17.3 PDF 文本可读不代表图片可读

MinerU 的 Markdown 可能成功提取正文和图注，但图片资源可能缺失。读取文本、读取图像、理解图表是三个不同层次的问题，不能用正文 OCR 结果替代图像读取。

17.4 不能把 PDF 纯文本抽取当作页面渲染

PDF 文本抽取适合查找图注和正文，不适合观察曲线、坐标轴、图例和版面。需要总结图表时，必须读取真实图片，或把 PDF 对应页面渲染成图像后再分析。

17.5 先查工具，再写命令

本次过程中曾尝试使用pdftoppm和fitz，但当前 Windows 环境没有pdftoppm，虚拟环境中也没有fitz。因此命令不能凭经验假设存在。排错时应先执行：

Get-Commandpdftoppm,magick,mutool,gswin64c-ErrorAction SilentlyContinue python-c"import importlib.util as u; print(bool(u.find_spec('fitz')))"

如果工具不存在，应改用已安装的工具或明确安装依赖，而不是继续重复失败命令。

17.6 优先使用当前版本的真实帮助信息

MinerU 不同版本的命令参数可能不同。应先执行：

python-m mineru.cli.client--help python-m mineru.cli.models_download--help

再复制参数。本文命令依据 MinerU3.4.4的实际帮助信息整理。

17.7 Windows 路径必须谨慎处理

中文路径、空格、括号和特殊字符都可能导致命令解析问题。PowerShell 中优先使用：

-LiteralPath'完整路径'

命令参数中的路径统一使用单引号。脚本中则使用变量保存路径，减少重复输入和拼写错误。

17.8 先做小样本测试

不要一开始处理整本书或数百页论文。先转换前 1～2 页，确认模型、后端、公式、表格和图片都正常，再进行完整转换。这样可以快速区分“环境问题”和“文档本身的问题”。

17.9 先使用稳定后端，再追求高精度

pipeline更适合作为入门和批量处理的起点。hybrid-engine的图表分析能力更强，但需要更多模型和计算资源。新手遇到卡顿或失败时，应先回到pipeline验证基本链路。

17.10 解析结果必须人工核验

对于科研论文，以下内容都不应盲信：

• OCR 识别出的数字和单位；
• 公式中的上下标；
• 表格中的列关系；
• 图注和图内文字；
• 页眉页脚和参考文献编号。

MinerU 负责提高整理效率，不能替代对原始论文的最终核验。

十八、结语

MinerU 的完整使用链路并不只是“安装一个 Python 包，然后打开 Markdown”。真正可靠的流程是：先确认 Python 和 MinerU 版本，再下载模型，使用稳定后端完成小样本测试，最后检查 Markdown 与图片资源是否匹配。

对于论文阅读，最重要的判断标准不是“转换命令是否退出”，而是：正文、公式、表格、图片和相对路径是否都能在目标阅读器中正确呈现。

发布前检查清单

• 代码块中的路径已替换为自己的实际路径
• 已说明 Python、MinerU 和操作系统版本
• 已给出安装、模型下载和转换命令
• 已解释images目录与 Markdown 的相对路径关系
• 已给出常见报错和排查办法
• 已提醒读者核验公式、表格和图表
• CSDN 发布时已删除个人隐私和不必要的本机路径