MinerU 版本升级指南：从 1.x 到 2.7 的完整迁移路径

MinerU 版本升级指南：从 1.x 到 2.7 的完整迁移路径

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

本文写给已安装 magic-pdf 1.x 或 mineru 2.x、准备升级到最新 2.7 系列的用户。内容覆盖版本路径选择、环境检查与备份、升级操作、破坏性变更核对与回滚，全程按步骤执行即可。

MinerU 是把 PDF、图片和 Office 文档转换成 Markdown 与 JSON 的文档解析工具。如果你的环境里装着旧版本、想换到新版本，这篇文章带你完整走一遍版本升级流程。读完后，你能独立完成升级、验证结果是否正确，并在出问题时快速回退到旧版本。

先查当前版本，再选升级路径

一条命令确认你装的是哪个版本：

mineru --version

如果还在 1.x，命令是magic-pdf --version。版本号查清后，按下面的路径对号入座：

路径上有三个要点：

• 1.x 升上去变更最多。2.0.0 的包名、命令名两项破坏性变更必须先处理，否则脚本会直接报错。
• 2.0 到 2.4 升上去要留意 VLM 模型：2.5 起 vlm 后端不再支持 MinerU2.0-2505-0.9B 模型，最后一个支持它的版本是 2.2.2。业务依赖旧模型就先锁定 2.2.2，再评估升级。
• 2.5、2.6、2.7 属于同一大版本内的小升级，直接更新包即可。注意 2.7.0 起默认解析后端从pipeline切换到hybrid-auto-engine，输出细节可能有差异，可用-b pipeline切回旧后端。

动手前：查四项，备份一个文件

先确认环境满足基线要求：

备份只做一件事，就拷一个文件：

cp ~/.mineru.json ~/.mineru.json.backup

mineru.json记录了本地模型路径和相关配置，回退时靠它恢复旧环境。如果你把模型放在自定义目录，把路径抄一份下来。备份到此为止，不多做。

升级主流程，四步走完

第一步：卸载旧版本

目的：清掉旧包，让新包装进干净环境，避免新旧依赖互相打架。

uv pip uninstall magic-pdf -y uv pip uninstall mineru -y

预期结果：两条命令都无报错退出。提示"未找到该包"也没关系，说明这个环境本来就没装过。

第二步：安装新版本

目的：装最新的 2.7。2.7.0 起一条命令装齐全部可选后端，不用再逐个选模块。

uv pip install -U "mineru[all]"

预期结果：安装结束、无报错。只想要核心功能省空间，可改装uv pip install "mineru[core]"。

第三步：下载或更新模型

目的：2.x 有模型自动下载，但跨大版本升级时，建议显式跑一次内置下载命令，保证模型与新版匹配。

mineru-models-download

预期结果：模型落到本地缓存。命令按增量更新，已有文件不会重下。如果模型目录被移动过，会重新下到默认位置并更新mineru.json。

第四步：按需切换模型源

目的：环境访问不了 HuggingFace 时，在解析或下载模型前切到国内镜像。

设置环境变量export MINERU_MODEL_SOURCE=modelscope，再重跑mineru-models-download。

预期结果：模型改从 ModelScope 拉取，下载速度恢复正常。

破坏性变更速查：1.x 升上来要改什么

从 1.x 升上去，主要工作量在改代码和脚本，对照下面这张表逐行核对即可：

已在 2.x 的用户，只需关注默认后端切换这一条，包名与配置文件不变。

升级后怎么确认没问题

查一：版本号对。再跑一次mineru --version，应打印出 2.7.x。

查二：冒烟通过。用一份业务里真实的 1 到 2 页文档做测试：

mineru --version mineru -p sample.pdf -o out/

预期结果：解析无报错，out/目录下生成 Markdown 和图片。别一上来就批量跑，先让单份文档通过。

查三：模型齐全。冒烟时报模型缺失，重跑mineru-models-download做增量更新，已有文件不会重复下载。

卡住了？对照四个高频问题

现象：ModuleNotFoundError: magic_pdf，或提示命令不存在→ 可能原因：脚本还在用旧包名、旧命令 → 解决：import magic_pdf改为import mineru，命令里的magic-pdf换成mineru。

现象：模型下载失败或超时→ 可能原因：网络访问不了 HuggingFace → 解决：export MINERU_MODEL_SOURCE=modelscope，再重跑mineru-models-download。

现象：Linux 上解析输出缺字→ 可能原因：2.0 起改用 pypdfium2 渲染 PDF，系统缺 CJK 字体 → 解决：Ubuntu/Debian 执行sudo apt install fonts-noto-cjk && fc-cache -fv，重跑解析。

现象：vlm 后端起不来，或提示模型不对→ 可能原因：2.5 起不再支持旧的 MinerU2.0-2505-0.9B 模型 → 解决：下载 MinerU2.5 模型重跑；或锁定最后支持旧模型的版本 2.2.2。

实在不行，回滚

前提只有一个：~/.mineru.json.backup还在，旧模型文件没被删。满足的话，回滚就三行：

uv pip uninstall mineru -y uv pip install "magic-pdf==1.3.12" cp ~/.mineru.json.backup ~/.mineru.json

2.x 内部回退同理，锁定版本即可，例如uv pip install "mineru==2.6.7"。先回滚恢复业务，再慢慢查原因，别在生产环境里硬改。

收尾前，过一遍清单

• 版本路径以版本号为准，先跑mineru --version再动手

• 1.x 升级只改两样：包名和命令行，配置项自动迁移

• 依赖旧 vlm 模型的业务，先锁 2.2.2 再评估升级

• 备份就一个文件：~/.mineru.json，升级期间留着别删

• 已查清当前版本，选定升级路径

• 已备份~/.mineru.json

• 已卸载旧包并装好mineru[all]

• 已跑mineru-models-download

• 样例 PDF 冒烟测试通过

• 回滚命令已验证可用

升级本身只是卸载、安装、验证三步，真正花心思的是改掉几处旧导入语句；备份在手，随时能退，升级这件事就没有什么好怕的。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU