最近需要把一些 PDF、扫描件之类的文档转成 Markdown，于是试了一下 MinerU。MinerU 是 OpenDataLab 开源的文档解析工具，支持 PDF、图片、Office 文档等格式，可以做 OCR、表格识别、公式识别，并输出 Markdown、HTML 等结果。简单说，就是把原来很难直接复制整理的文档，尽量转换成适合后续编辑和检索的结构化文本。

我平时在本机上使用 Python 时，一般会把 Conda 当作环境管理工具：不同用途单独建环境，尽量不往 base 环境里塞东西。这样做的好处是排查问题时边界比较清楚，某个工具出了问题，基本只需要检查它自己的环境，不会和系统 Python、其他项目依赖混在一起。

MinerU 官方文档里推荐使用 uv 安装依赖。uv 的速度确实很快，但如果直接在当前目录或家目录下执行安装命令，很容易让包落到一个自己没注意到的虚拟环境里。对我来说，更顺手的方式是保留原来的习惯：继续用 Conda 管 Python 版本和环境隔离，再用 uv 在这个 Conda 环境里安装 MinerU。

不过安装这类 Python 工具的时候，最容易踩的坑往往不是工具本身，而是 Python 环境。比如照着官方文档安装完之后，执行：

mineru

结果提示：

1	zsh: command not found: mineru

这通常不是 MinerU 没装上，而是装到了另一个 Python 环境里，当前 shell 找不到对应的可执行文件。我的情况更典型一点：一开始用 uv 在家目录下创建了 ~/.venv，后来发现这个环境里的 Python 是 3.14，而 MinerU 官方要求 Python 版本为 3.10 到 3.13。既然本机平时本来就用 Conda 管理 Python 环境，那么更干净的做法就是：

Conda 负责创建和切换 Python 环境，uv 负责在这个环境里安装 Python 包。

前置条件

已经安装 Conda 或 Miniforge；
macOS 或 Linux 终端环境；
希望单独创建一个 mineru 环境，不污染 base 环境；
Python 版本选择 3.13，避开 3.14 可能带来的兼容性问题。

新建 Conda 环境

先创建一个专门给 MinerU 用的环境：

1 2	conda create -n mineru python=3.13 -y conda activate mineru

确认当前 Python 已经切换到新环境：

1 2	which python python -V

正常情况下，which python 应该输出类似：

1	/Users/username/miniforge3/envs/mineru/bin/python

只要路径里包含 envs/mineru/bin/python，就说明现在已经在正确的 Conda 环境里了。

安装 uv

在这个 Conda 环境里安装 uv：

1 2	python -m pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple python -m pip install uv -i https://mirrors.aliyun.com/pypi/simple

这里使用 python -m pip，是为了确保 pip 一定来自当前 Conda 环境，而不是系统里的另一个 Python。

使用 uv 安装 MinerU

接下来用 uv 安装 MinerU。关键是明确指定当前 Conda 环境中的 Python：

1	python -m uv pip install --python "$CONDA_PREFIX/bin/python" -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple

这样 uv 只负责解析和安装依赖，包还是会进入当前的 mineru Conda 环境里，不会偷偷跑到 ~/.venv 或其他环境中。

安装完成后验证：

1 2	which mineru mineru --help

正常情况下，which mineru 应该输出类似：

1	/Users/username/miniforge3/envs/mineru/bin/mineru

如果 mineru --help 能正常显示帮助信息，说明命令已经可以在当前环境里使用了。

国内网络环境下的模型来源设置

如果访问 HuggingFace 不稳定，可以在运行前加上：

1	export MINERU_MODEL_SOURCE=modelscope

如果确认以后都要这样使用，也可以写入 ~/.zshrc：

1 2	echo 'export MINERU_MODEL_SOURCE=modelscope' >> ~/.zshrc source ~/.zshrc

基本使用方式

以后使用 MinerU 时，先激活环境：

1	conda activate mineru

然后执行解析命令：

1	mineru -p input.pdf -o output

如果是 CPU 环境，可以显式指定 pipeline 后端：

1	mineru -p input.pdf -o output -b pipeline

不用的时候退出环境：

1	conda deactivate

清理之前的错误环境

如果之前已经在家目录下创建过 ~/.venv，并且确认不再需要，可以直接删除：

1	rm -rf ~/.venv

这是删除整个虚拟环境目录，不需要逐个卸载里面的包。删完之后可以确认一下：

1	ls ~/.venv

如果提示 No such file or directory，就是已经删干净了。

常见问题

conda activate 之后，which python 还是 ~/.venv/bin/python

这说明当前 shell 里可能还激活着旧的虚拟环境，先执行：

deactivate
conda deactivate
conda activate mineru
rehash
which python

如果还是不对，就检查 ~/.zshrc 里是否手动把 ~/.venv/bin 加到了 PATH 前面：

1	grep -n ".venv" ~/.zshrc

如果有类似下面这一行：

1	export PATH="$HOME/.venv/bin:$PATH"

就把它删除或注释掉，然后重新加载 shell 配置。

mineru 装上了，但 which mineru 为空

先确认当前 Python 环境：

1 2	which python python -m pip show mineru

如果 python -m pip show mineru 能看到包信息，但 which mineru 为空，大概率还是 PATH 或环境没激活的问题。回到前面几步，确认 conda activate mineru 后再执行。

小结

这套方案的好处是边界清楚：Conda 管 Python 版本和环境隔离，uv 管包安装速度和依赖解析。以后只要记住：

1 2	conda activate mineru mineru --help

能跑通，基本就不会再被 zsh: command not found: mineru 绊住了。

愉快地解析你的文档吧。