MinerU Python 3.10-3.13 全版本兼容：3 种安装方式 10 分钟跑通
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
本地开发机跑着 3.11，CI 上却是 3.12，一换环境mineru就装不上或依赖打架，这是文档解析类项目最常见的翻车现场。MinerU 是把 PDF、图片、DOCX/PPTX/XLSX 解析成 Markdown/JSON 的工具，当前版本 3.4.4，官方明确支持 Python 3.10 到 3.13 共 4 个版本。看完本文你可以知道：每个版本装什么、装完怎么验证、哪些坑已经有人踩过。
先说结论（TL;DR）
- 支持 Python 3.10 / 3.11 / 3.12 / 3.13 共 4 个版本；Windows 上因依赖限制只到 3.12。
- 一条命令装全功能：
uv pip install -U "mineru[all]"，轻量场景用mineru[core]。 - 版本门槛写死在
requires-python = ">=3.10,<3.14"，3.9 或 3.14 会在安装阶段直接报错，不会装到一半才炸。 - 纯 CPU 环境加
-b pipeline就能跑；首次运行自动下载模型，Hugging Face 不通就设MINERU_MODEL_SOURCE=modelscope。
环境要求速查
| Python 版本 | 一句话评价 | 适用场景 |
|---|---|---|
| 3.10 | 兼容下限，第三方库适配最宽 | 生产环境 |
| 3.11 | 性能与兼容性平衡最好 | 推荐默认选择 |
| 3.12 | 错误信息更详细，调试友好 | 开发/测试环境 |
| 3.13 | 最新特性，但 Windows 不支持 | Linux/macOS 尝鲜 |
另外两个硬门槛：Linux 需 2019 年及以后发行版，macOS 需 14.0 以上，不满足的环境不建议折腾。
动手配置
方式一：uv 或 pip 直接安装，适合绝大多数场景，实测在 3.11 上装mineru[all]约 2~5 分钟（取决于网络）。
uv pip install -U "mineru[all]" # 或者 pip install -U "mineru[all]" # 不需要 vllm / lmdeploy / s3 时，装轻量的 core 即可 uv pip install "mineru[core]"方式二：源码安装，方便改代码调试。
git clone https://gitcode.com/GitHub_Trending/mi/MinerU cd MinerU uv pip install -e ".[all]"方式三：Docker 部署，只适用于 Linux 和支持 WSL2 的 Windows，macOS 不要用（容器里调不到 MPS/MLX 加速）。
docker compose -f docker/compose.yaml --profile api up -d装完验证一下，纯 CPU 环境指定pipeline后端即可：
mineru -p demo/pdfs/demo1.pdf -o out -b pipeline输出目录里能看到生成的 Markdown 和图片，说明环境已跑通。
它为什么能做到（原理揭秘）
用版本范围把边界画死
pyproject.toml里直接声明：
requires-python = ">=3.10,<3.14"pip 在解析依赖前就会做这个检查 → 所以 3.9、3.14 环境会在安装第一步被拦下，报错信息明确指向 Python 版本，而不是等到某个 wheel 装不上才发现。
用 classifiers 声明 4 版本矩阵
classifiers = [ "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", ]这组元数据发布到 PyPI 后，支持范围一目了然 → 用户不用翻 issue 去猜"到底支不支持 3.13"。
按平台自动挑加速引擎
[all]这个扩展包是这样拼的：
all = [ "mineru[core]", "mineru[s3]", "mineru[mlx] ; sys_platform == 'darwin'", "mineru[vllm] ; sys_platform == 'linux'", "mineru[lmdeploy] ; sys_platform == 'win32'", ]同一条安装命令在 macOS 装 MLX、Linux 装 vllm、Windows 装 lmdeploy → 三种系统的推理加速引擎自动就位，不用手动挑 wheel。这也是 Windows 只到 3.12 的原因：lmdeploy 依赖链里的ray尚未提供 Windows + Python 3.13 的包。
踩坑与排错
坑 1：Linux/WSL2 上 import 报ImportError: libGL.so.1
- 症状：
mineru -p ...一启动就抛libGL.so.1: cannot open shared object file。 - 原因：opencv 这个核心依赖需要系统级 libgl，最小化系统和 WSL2 默认没装。
- 解决：
sudo apt-get install libgl1-mesa-glx坑 2：解析结果中文缺字
- 症状：输出 Markdown 正常，但渲染出的图片里部分汉字是空白。
- 原因：MinerU 2.0 起用 pypdfium2 渲染 PDF，发行版缺 CJK 字体时中文会丢。
- 解决：
sudo apt update sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv用 Docker 部署的话镜像里已自带这些字体，可以绕开这个问题。
坑 3：Windows + Python 3.13 装完跑不了 GPU 加速
- 症状：3.13 环境安装"成功"，但 vlm 加速相关依赖报错或回退到 CPU。
- 原因：
ray不支持 Windows 上的 3.13，官方 Windows 上限就是 3.12。 - 解决：降级环境而不是硬装：
conda create -n mineru python=3.12 -y conda activate mineru uv pip install -U "mineru[all]"进阶技巧
调渲染和线程参数。PDF 渲染默认 3 个线程、300 秒超时，高并发服务化部署时容易抢 CPU，用环境变量压一压：
export MINERU_PDF_RENDER_THREADS=4 export MINERU_PDF_RENDER_TIMEOUT=600 export MINERU_INTRA_OP_NUM_THREADS=4 export MINERU_INTER_OP_NUM_THREADS=2CI 里跑 4 版本矩阵。确认代码在全部支持版本可用，配置很短：
jobs: test: strategy: matrix: python-version: ["3.10", "3.11", "3.12", "3.13"] steps: - uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - run: pip install -e ".[test]" - run: pytest tests/一句话收尾
挑一个你环境里最容易出问题的 Python 版本，现在跑一条uv pip install -U "mineru[all]"加验证命令，装不上再来对一遍上面三个坑。
【免费下载链接】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），仅供参考
