解决MinerU项目中magic-pdf安装版本不匹配问题

在MinerU项目使用过程中，部分MacOS用户遇到了magic-pdf安装后版本显示异常的问题。具体表现为安装最新1.3.4版本后，系统却显示为0.6.1版本，并出现"Error: No such option: -p"的错误提示。

问题背景

该问题主要出现在MacOS 12.5.1系统上，使用Apple M1 Max芯片的设备。用户按照标准流程创建conda环境并安装magic-pdf后，版本显示异常。经过分析，这实际上是一个环境兼容性问题，而非软件本身的缺陷。

根本原因分析

经过技术排查，发现问题的核心在于：

1. Python版本与系统版本的兼容性问题：Python 3.13需要MacOS 13及以上版本才能完全兼容
2. onnxruntime依赖要求：在MacOS 11/12系统上，Python 3.13安装的onnxruntime存在兼容性问题
3. 依赖解析冲突：pip在解析依赖时可能选择了不兼容的旧版本magic-pdf

解决方案

针对此问题，我们推荐以下几种解决方案：

方案一：升级MacOS系统

将系统升级至MacOS 13或更高版本，这是最彻底的解决方案。升级后可以：

• 确保Python 3.13环境完全兼容
• 避免onnxruntime等依赖的兼容性问题
• 获得更好的性能表现

方案二：使用Python 3.12环境

如果暂时无法升级系统，可以创建Python 3.12的conda环境：

conda create -n mineru python=3.12 -y
conda activate mineru
pip install -U "magic-pdf[full]"

Python 3.12在MacOS 11/12系统上有更好的兼容性，可以避免onnxruntime的版本冲突。

方案三：手动指定依赖版本

对于高级用户，可以尝试手动指定关键依赖的版本：

pip install onnxruntime==1.21.0 magic-pdf==1.3.4

这可以强制使用兼容MacOS 11/12系统的onnxruntime版本。

验证解决方案

安装完成后，可以通过以下命令验证版本是否正确：

magic-pdf --version

正确安装后应显示为1.3.4版本。如果仍然存在问题，建议彻底删除环境后重新创建：

conda env remove -n mineru
conda create -n mineru python=3.12 -y
conda activate mineru
pip install -U "magic-pdf[full]"

总结

MinerU项目中magic-pdf的版本显示问题主要源于系统环境与Python版本的兼容性。通过升级系统或使用兼容的Python版本，可以有效解决这一问题。建议MacOS用户优先考虑升级系统或使用Python 3.12环境，以获得最佳兼容性和稳定性。