MinerU安装教程：pip、Docker、桌面客户端三种方式与模型下载源配置

MinerU 安装方式怎么选

最快的路径有两条：只想试用和轻度使用，直接上 mineru.net 在线版或桌面客户端，零安装；要做开发集成或批量处理，走 pip 或 Docker。本文的命令与硬件要求均出自官方 README（2026 年 9 月抓取），细节有出入时以官方文档为准。如果还不清楚这个工具的定位，先看MinerU 是什么再回来装也不迟。

先给一张硬件要求表，装之前对照自查（官方 README）：

项	pipeline 后端	vlm / hybrid 引擎	http-client 模式
最低显存	4GB（GPU）	8GB	2GB，GPU 非必需
内存	最低 16GB，建议 32GB 以上	同左	最低 16GB
磁盘	最低 20GB，建议 SSD	同左	最低 2GB
Python	3.10~~3.13（Windows 为 3.10~~3.12）	同左	同左

没有独立显卡的机器不用退场：pipeline 后端支持纯 CPU 推理，只是速度慢一些。

方式一：pip 安装

pip 是最通用的方式，Windows、Linux、macOS 三平台都支持。官方推荐用 uv 管理依赖，两条命令完成安装：

pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

mineru[all] 包含全部核心功能，适合大多数用户；只需要轻量客户端或要指定 VLM 推理框架的场景，参考官方文档的扩展模块安装指南。PyPI 包名为 mineru，这是 pip 安装正确包名的关键，装错同名包会浪费不少排查时间。

想跟进仓库最新代码或做二次开发，从源码安装：

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

装完直接用命令行验证。有 GPU（Volta 架构及更新，或 Apple Silicon）的设备：

mineru -p <input_path> -o <output_path>

不满足 GPU 要求或想跑纯 CPU，显式指定 pipeline 后端：

mineru -p <input_path> -o <output_path> -b pipeline

-p 接输入路径，-o 接输出目录，支持本地 PDF、图片、DOCX、PPTX、XLSX 文件或整个目录。跑通一次，说明环境、模型、依赖全部就位。

模型下载源配置：慢的根源在这里

首次运行会下载模型，下载慢是安装环节最常见的抱怨。3.4 版本（2026-06-18，官方 Changelog）专门重做了这块：新增自动模型源选择，首次安装按当前网络环境挑选更优的下载源；下载前优先检查本地已缓存的模型文件，命中缓存直接复用，不再重复下载。

对三类场景收益明显：国内网络首次安装自动避开慢源；多机部署时第二台机器起直接命中缓存；反复升级版本时只增量拉取变化的模型。更细的源配置和本地模型指定方法，见官方文档的 Model Source 一节（opendatalab.github.io/MinerU/usage/model_source/）。以我的安装经验，先跑一次让自动选源生效，比手动改配置文件更省事。

方式二：Docker 部署

Docker 的价值在环境一致性：torch、CUDA、系统依赖全部打包好，绕开本机环境的各种兼容问题。按官方 README，Docker 部署只支持 Linux，以及支持 WSL2 的 Windows；macOS 用户不用 Docker，直接用上面的 pip 方式。具体镜像地址、端口映射与启动命令以官方文档的 Docker Deployment 一节为准，这里不抄写易过期的细节。

适用判断很简单：团队要统一环境、或要把解析服务跑在服务器上长期供 API 调用，Docker 是首选；个人笔记本临时转几个文件，pip 更快。

装完之后：API 服务与多机路由

3.0 起 MinerU 的 CLI 以 mineru-api 为编排客户端运行，不指定 --api-url 时会自动拉起本地临时服务（官方 Changelog），单机命令行和 API 服务是同一套底座。mineru-api 提供两类端点：异步任务端点 POST /tasks 负责任务提交、状态查询与结果获取，同步解析端点 POST /file_parse 向后兼容旧插件。要搭多机或多 GPU 的解析集群，还有 mineru-router 做统一入口部署与任务路由，接口与 mineru-api 完全兼容，自带任务负载均衡。

这套组件决定了安装方式的边界：pip 适合开发与单机，Docker 加 router 适合服务化。把解析服务接进 Dify、FastGPT 或 MCP 客户端的做法，见MinerU 的 RAG 与 MCP 集成指南；装好后怎么评估转换质量，看PDF 转 Markdown 实战。

方式三：桌面客户端与在线版

mineru.net 是一站式入口，网页版、桌面客户端、API 三种形态都在这里。网页版登录即用，功能和客户端一致，适合临时处理几份文件、或者下载模型前先验证解析效果；桌面客户端覆盖 Windows、Linux、macOS，给不想碰命令行的用户。官方 README 明确建议：文档解析是复杂任务，复杂版面、扫描件、手写内容的解析效果未必处处如意，先拿在线 demo 验证自家文档的解析质量，再决定用哪种部署方式——这个顺序能省掉很多无效部署。

三种方式对比

维度	pip / uv	Docker	在线版 / 客户端
上手速度	十分钟级（含模型下载）	拉镜像后分钟级	打开即用
可控性	高，可改后端与模型源	高，环境完全固定	低，只能用官方参数
前置条件	Python 3.10~3.13	Linux 或 WSL2	浏览器或装客户端
适用人群	开发者、数据处理	运维、团队私有化	非技术用户、轻度使用

经验顺序是：先用在线版验证效果，效果好再按使用深度选 pip 或 Docker。直接从 pip 开始装反而容易在效果不达预期时白折腾一轮环境。

常见安装坑与排查

四个高频问题的处理思路：

模型下载慢或失败：3.4 起自动选源加缓存复用已解决大半，升级到最新版重试；仍慢就按官方 Model Source 文档手动指定源。
显存不足：改用 pipeline 后端跑纯 CPU 模式（-b pipeline），代价是速度下降，这是工程建议；8GB 以上显存才能跑 vlm/hybrid 引擎。
Windows 下装完没有 CUDA 加速：属于高频问题，官方 FAQ 有专门的 Windows CUDA 加速条目，按步骤核对驱动与 torch 版本。
Python 版本不匹配：Windows 因关键依赖 ray 的限制只支持 3.10~3.12，别用 3.13；macOS 需要 14.0 以上。

排查无果时，官方 FAQ（opendatalab.github.io/MinerU/faq/）覆盖了绝大多数已知问题，也可以把报错和样例文件提到 GitHub issue。

常见问题

mineru 教程哪里找，怎么快速上手？

最短路径是打开 mineru.net 在线版直接上传文件试效果；本机安装则用 pip 安装 mineru 包，跑 mineru -p 输入路径 -o 输出路径 完成首次解析。进阶用法看官方文档与本站的转换实战篇。

mineru docker 部署有什么限制？

Docker 方式只支持 Linux 和启用 WSL2 的 Windows，macOS 需改用 pip 安装（官方 README）。镜像内置 torch、CUDA 等依赖，适合团队统一环境与服务器长期运行，具体镜像与启动参数以官方 Docker 部署文档为准。

mineru 安装后模型下载到哪里，能离线吗？

3.4 版本起模型下载前会优先检查本地缓存文件，命中即复用（官方 Changelog），缓存路径与本地模型指定方法见官方 Model Source 文档。缓存完整后可以离线推理，适合内网环境部署。