MinerU PDF转Markdown的macOS安装避坑指南：3条命令搞定arm64依赖报错
【免费下载链接】MinerUA high-quality tool for convert PDF to Markdown and JSON.一站式开源高质量数据提取工具，将PDF转换成Markdown和JSON格式。项目地址: https://gitcode.com/OpenDataLab/MinerU
MinerU 是一款把 PDF 转成 Markdown 和 JSON 的开源文档解析工具。在 Apple Silicon 的 Mac 上安装时，常遇到sgl-kernel无可用轮子的报错。这篇给你一条完整的 macOS 安装与排错路线。
📌 先说结论
别纠结报错，直接装 core 版本：pip install "mineru[core]"。它打包了 vlm、pipeline、gradio 三个功能集，日常 PDF 转 Markdown、JSON 的场景全都能覆盖，同时绕开了 arm64 缺预编译包的那批依赖。macOS 14.0 以上的 Mac 用这套组合最稳。
方案选型：core、Docker、源码三条路怎么选
| 方案 | 适合谁 | 优点 | 局限 |
|---|---|---|---|
pip install "mineru[core]" | 日常 Mac 用户 | 一条命令装完，体积可控，核心转换能力完整 | 不带 vllm 等服务端加速扩展 |
| Docker 容器 | 想跑全量功能、有运维经验的人 | 功能完整、环境隔离 | 官方文档建议 macOS 用户优先用本地 pip 安装；资源占用偏高 |
| 源码编译 | 需要改代码、定制依赖的人 | 完全可控，可针对个别依赖打补丁 | 技术门槛高，编译和依赖坑多 |
⚠️ 坑的现场：sgl-kernel 为什么在 arm64 上装不上
如果你之前直接装过完整包，多半会看到这样的报错：
ERROR: Could not find a version that satisfies the requirement sgl-kernel
No matching distribution found for sgl-kernel (from versions: none)
根因一句话：sgl-kernel 是带 C++ 编译件的底层依赖，上游还没给macosx_15_0_arm64这个平台出预编译包，pip 在 Apple Silicon 上找不到可安装的二进制，整条依赖链就跟着失败。不是你网络差，也不是 pip 版本旧，升级 pip 解决不了它。
安装实操：在 macOS 上装 mineru[core]
先确认 Python 版本，MinerU 目前支持 3.10–3.13，超出范围建议先处理：
python3 --version建一个专用虚拟环境并激活，避免依赖污染系统 Python：
python3 -m venv mineru_env source mineru_env/bin/activate升级一下 pip（旧版本对新 wheel 索引支持不全），再装 core 版本。注意mineru[core]必须加引号，否则 shell 会把方括号当通配符解析：
pip install -U pip pip install "mineru[core]"用 uv 的同学一行替代即可：uv pip install "mineru[core]"，效果相同。
✅ 验证与排错：装完怎么确认没白装
跑一条命令验证安装：
python -c "import mineru; print(mineru.__version__)"能打印出版本号就齐活了。几个常见情况：
- 看到
ModuleNotFoundError: No module named 'mineru'→ 虚拟环境没激活，先执行source mineru_env/bin/activate再重试。 - 再次出现
sgl-kernel相关报错 → 说明你装的是mineru[all]之类的完整功能集，改回mineru[core]重新安装。 - 首次运行长时间停在下拉里 → 这是 MinerU 在自动下载模型权重，属于正常现象，也可以提前用
mineru-models-download预取。 - 怀疑依赖冲突时，跑
python -m pip check，缺什么包它会直接点名。
写在最后：几个高频问题
问：mineru[core] 会少功能吗？日常场景不缺：PDF、DOCX、PPTX、XLSX 转 Markdown 和 JSON、Gradio WebUI 都在，缺的主要是 vllm 这类只在 Linux 上部署的加速服务。真有这需求，放到 Linux 机器上装完整版更合适。
问：模型权重下载太慢怎么办？首次运行才拉模型，之后都走本地缓存。可以先用mineru-models-download预取，或给 pip 配国内镜像源加速装包。
更多环境要求与安装选项，可以看项目里的docs/zh/quick_start/目录，里面有完整的软硬件支持说明。
【免费下载链接】MinerUA high-quality tool for convert PDF to Markdown and JSON.一站式开源高质量数据提取工具，将PDF转换成Markdown和JSON格式。项目地址: https://gitcode.com/OpenDataLab/MinerU
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
