MinerU 版本升级：4步完成1.x到2.x的完整升级，避开不兼容的坑

MinerU 版本升级4步完成1.x到2.x的完整升级避开不兼容的坑【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU你是否在给 MinerU 做版本升级时被找不到 magic_pdf 模块之类的报错卡住过MinerU 这个把 PDF、Office 文档转成 Markdown 的解析工具老用户从 1.x 升上来时最容易在包名和命令变更上翻车。其实这条升级路线并不复杂真正的分叉只有一个你还在不在 1.x 那个magic-pdf时代。这篇把升级主线、3个高频坑、验证和回退方法一次讲清30分钟内就能完成切换不用反复翻文档。 定位你的版本动手前先花30秒确认你在哪一档如果你一直在用的命令还是magic-pdf说明你在 1.x 时代如果mineru已经装好直接看版本号对号入座你的现状所属版本线升级方式备注命令还是magic-pdf1.x 时代大版本升级包名、命令、配置都变了mineru输出 2.0.x2.0 系列常规升级老脚本改名后可兼容mineru输出 2.1 及以上2.x 系列直接更新小版本特性更新覆盖安装即可一句话说透1.x 的用户要跨这次升级里最大的一道坎包名、命令、配置文件全换了得顺手改脚本而 2.x 之间的升级就是覆盖安装 补下模型跟升级任何 Python 包没区别。对了不管哪个版本MinerU 干的事都一样把杂乱 PDF 变成结构化 Markdown整个解析流程长这样 走通升级主线备份配置和模型先看整条主线5步按顺序走别跳步动任何手脚前先备份用户目录下的配置文件和模型缓存。模型有好几个 G重下很慢配置里存着你自定义的公式分隔符、本地模型路径这些设置丢了重写麻烦。cp ~/.mineru.json ~/.mineru.json.backup cp -r ~/.cache/mineru ~/mineru_models_backup干净卸载旧版本这一步很多人会忘——1.x 和 2.x 是两个不同的包名不卸干净的话新旧两份会共存命令指向的可能是旧版比不升级还乱。uv pip uninstall magic-pdf mineru -y安装新版本其实很简单新版开箱即用一条命令装全所有可选后端如果只跑核心解析功能也可以把后缀换成mineru[core]省空间。uv pip install -U mineru[all]下载新模型新版对应的是新一代模型文件不会自己冒出来。跑一次内置下载命令它会增量补齐缺失的模型并自动生成新的mineru.json配置后面首次解析才不会报错。mineru-models-download⚠️ 避开3个高频坑依赖冲突导致安装失败现象是安装中途报版本冲突或者装完 mineru 一运行就报缺模块。多半是老环境历史依赖太多新装的东西往上叠就打架了。最稳的办法是开一个干净的虚拟环境重装uv venv mineru-env source mineru-env/bin/activate uv pip install mineru[all]模型下载卡住或超时现象是下载命令长时间没动静或报连接失败。通常是当前网络访问不了默认模型源切换 ModelScope 源一般就能通如果是常驻服务机把这个环境变量固定写进启动脚本。export MINERU_MODEL_SOURCEmodelscope mineru-models-download老脚本还在调用 magic-pdf现象是新版装好了原有脚本和定时任务却报找不到命令。这一步最容易漏2.0.0 起包名改了脚本里的magic-pdf命令和import magic_pdf都得换成mineru。先搜出所有调用位置再全局替换grep -rn magic-pdf\|magic_pdf scripts/升级前后对照方面1.x 时代2.x 现版本调用方式magic-pdf命令mineru命令也可起 API 服务和 WebUI模型管理手动下载、手动放置首跑自动下载一条命令增量更新支持文档以 PDF 为主PDF 和 Office 文档原生解析默认后端仅 pipelinehybrid 自动选择扫描件支持109种语言最低显存6GB8GBTuring 及以后架构这5项里模型管理和默认后端的变更对普通用户是完全透明的你什么都不用做。必须手动处理的是调用方式把脚本和定时任务里的magic-pdf找出来改名就行。显存从 6GB 提到 8GB用老卡跑的朋友要留意一下。✅ 验证、回退与后续关注最后确认升级真的成功。最短的验证就是直接解析仓库里的示例文件输出目录里出现 Markdown 和图片就说明没问题mineru -p demo/pdfs/demo1.pdf -o output/如果新版实在跑不动别急回退路线就是升级的逆操作卸掉新包、装回旧包、恢复备份的配置核心命令就一条uv pip install magic-pdf1.3.12后续关注3个渠道就够了官方 Release 页Discord 社区官方文档更新日志【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考