Junya Yang | Academic Homepage

Appearance

PostTools / Conda

UV

2026-09-23
Back to Blog

在 Conda 环境中使用 uv 管理 Python 包 ​

目标 ​

本笔记采用的分工是：

  • Conda 管理环境本身：创建、删除、激活环境，以及 Python 版本、CUDA、PyTorch 等底层依赖。
  • uv 管理 Python 项目的依赖解析、安装、pyproject.toml 和 uv.lock。

这样既可以通过 conda activate 随时切换 RNA 工具环境，也可以保留 uv 的快速解析和可复现依赖锁定。

text
Conda 环境（rna-design）
├── Python / CUDA / PyTorch / 系统二进制依赖
└── 由 uv 安装的 Python 包

项目目录（course_project）
├── pyproject.toml  # 声明项目需要什么包
└── uv.lock         # 锁定可复现的精确版本

创建并激活环境 ​

bash
conda create -n rna-design python=3.12
conda activate rna-design

激活后，安装到这个环境的包在任意目录都可使用；cd 只是在切换项目目录，不是在切换 Python 环境。

bash
conda activate rna-design
python your_script.py

初始化 uv 项目 ​

在项目目录中只需初始化一次：

bash
cd ~/Research/course_project
uv init --bare

这会创建 pyproject.toml。第一次添加依赖后，uv 会生成 uv.lock。

--active 的作用 ​

--active 要求 uv 使用当前已经激活的 Conda 或虚拟环境，而不是默认使用或创建项目目录中的 .venv。

bash
conda activate rna-design
cd ~/Research/course_project
uv add --active viennarna

这条命令会：

  1. 将 viennarna 安装到当前的 rna-design Conda 环境；
  2. 将它写入 pyproject.toml；
  3. 更新 uv.lock；
  4. 不创建，也不使用项目默认的 .venv。

--active 仅影响当前命令。因此如果采用 Conda + uv 模式，下列项目命令都建议带上它：

bash
uv add --active 包名
uv sync --active
uv run --active python your_script.py

不带 --active 的 uv run、uv sync 或 uv add 通常会优先使用项目中的 .venv。

如果不在项目目录，可明确指定项目位置：

bash
uv --directory ~/Research/course_project add --active viennarna

uv 安装包的不同方式 ​

命令安装位置更新项目文件适用场景
uv add 包名项目 .venvpyproject.toml、uv.lock标准 uv 项目
uv add --active 包名当前 Conda 环境pyproject.toml、uv.lockConda 管环境、uv 管项目依赖
uv pip install 包名当前激活的 Conda/虚拟环境不更新长期工具箱或临时安装
uv sync [--active]项目 .venv 或当前环境不添加依赖按锁文件重建或同步环境
uv tool install 工具名uv 自己的隔离工具环境不更新ruff、black 等命令行工具
uvx 工具名 / uv run --with 包名临时隔离环境不更新一次性试用或运行

uv add ​

适合应该由项目长期依赖的库，例如 ViennaRNA、NumPy、SciPy、Pandas 和 NUPACK。

bash
uv add --active viennarna numpy scipy pandas matplotlib

uv pip install ​

接近加速版 pip install：它直接向已激活的环境安装包，不记录项目依赖。

bash
conda activate rna-design
uv pip install viennarna

这适合将 rna-design 当作个人 RNA 工具箱。缺点是别人无法仅通过项目的 pyproject.toml 和 uv.lock 重建该安装。

uv sync ​

读取 pyproject.toml 与 uv.lock，将环境同步到被锁定的依赖集合：

bash
uv sync --active

默认进行精确同步，可能移除锁文件中没有的 Python 包。若 Conda 环境还包含需要保留的额外 Python 包：

bash
uv sync --active --inexact

针对 RNA 工具的建议 ​

优先用 uv 管理的项目依赖 ​

bash
uv add --active viennarna numpy scipy pandas matplotlib jupyterlab

NUPACK 从官网接受许可并下载匹配系统、Python 版本和架构的 wheel 后，可从本地目录安装：

bash
uv add --active --find-links /path/to/nupack/package nupack

更适合由 Conda 管理的内容 ​

  • Python 版本；
  • CUDA 与 GPU 运行时；
  • PyTorch 等对 CUDA 版本敏感的包；
  • 只能通过 Conda/Bioconda 获取的系统工具或二进制依赖。

同一个 Python 包只应由一个工具管理。例如若 viennarna 已通过 uv add --active 安装，就不要再执行 conda install viennarna。

ViennaRNA 验证 ​

安装后可验证：

bash
uv pip list | grep -Ei 'vienna|rna'
uv run --active python -c "import RNA; print(RNA.__version__); print(RNA.__file__)"

也可以使用 Conda 明确指定环境：

bash
conda run -n rna-design python -c "import RNA; print(RNA.__version__)"

grep -Ei 'vienna|rna' 中：

  • -E 表示启用扩展正则表达式，因此 | 表示“或”；
  • -i 表示忽略大小写；
  • 'vienna|rna' 表示匹配名称中含有 vienna 或 rna 的行。

常见问题：激活 Conda 后仍使用错误的 Python ​

如果看到类似输出：

text
python: aliased to python3
pip: aliased to pip3

而 python 指向 Homebrew，而不是 Conda 环境，说明 shell alias 覆盖了 Conda 的解释器路径。当前终端可修复为：

bash
unalias python
unalias pip
rehash

再检查：

bash
which python
which pip
python -c "import sys; print(sys.executable)"

期望 Python 路径类似：

text
/opt/homebrew/Caskroom/miniforge/base/envs/rna-design/bin/python

若确实在 ~/.zshrc 中写了下列 alias，应删除或注释：

bash
alias python=python3
alias pip=pip3

推荐日常流程 ​

bash
conda activate rna-design
cd ~/Research/course_project
uv sync --active --inexact
uv run --active python your_script.py

当新增正式项目依赖时：

bash
uv add --active 包名

当只想在当前 Conda 工具箱里临时添加一个包时：

bash
uv pip install 包名