使用 UV 管理 Python 版本、虚拟环境及项目依赖（Debian/Ubuntu 详细教程）

uv 是基于 Rust 开发的新一代 Python 工具链，一站式替代 pyenv/venv/pip，原生支持 Python 版本管理、虚拟环境创建、依赖安装，核心优势为无需编译、速度极快、版本隔离、跨平台兼容，完美适配 Debian Bookworm（及 Ubuntu）系统，尤其适合 ComfyUI 等需要指定 Python 版本+独立依赖环境的项目。

一、前置说明

1. 系统适配：Debian 11/12（Bookworm）、Ubuntu 20.04/22.04/24.04（其他 Linux 发行版通用）；
2. 无权限要求：除系统基础网络操作外，全程无需 sudo，所有文件均安装在用户目录，不污染系统环境；
3. 核心能力：无需编译即可安装任意 Python 版本（预编译包）、毫秒级创建虚拟环境、依赖安装速度比 pip 快 10-100 倍；
4. 版本隔离：UV 管理的 Python 版本与系统默认 Python 完全独立，不会影响系统自带工具（如 apt/dpkg 依赖的 Python）。

二、第一步：全局安装 UV 工具

UV 提供单命令一键安装，无任何系统依赖，安装后全局可直接调用，步骤如下：

2.1 执行安装命令

# 全局安装 UV（自动适配系统架构，Linux/Mac/Windows 通用）
curl -LsSf https://astral.sh/uv/install.sh | sh

• 安装过程：自动下载对应系统的 UV 二进制文件，配置到用户环境变量（~/.cargo/bin 或 ~/.local/bin）；
• 耗时：10 秒内完成，无编译过程。

2.2 验证安装成功

安装完成后重启终端（让环境变量生效），执行以下命令验证：

# 查看 UV 版本，输出版本信息即安装成功
uv --version

成功输出示例

uv 0.4.17 (a1b2c3d 2026-02-03)

2.3 解决「command not found」报错

若重启终端后仍提示 uv: command not found，手动刷新环境变量即可：

# 适用于 bash 终端（Debian/Ubuntu 默认）
source ~/.bashrc

# 若为 zsh 终端（如 Oh My Zsh），执行
source ~/.zshrc

三、第二步：UV 管理 Python 版本（核心操作）

UV 内置 python 子命令，支持一键安装/卸载/切换/查看任意 Python 版本，直接下载官方预编译包，无需处理编译依赖，全程秒级完成。

3.1 核心命令：查看可安装/已安装的 Python 版本

3.1.1 查看 UV 支持安装的所有 Python 版本

# 列出所有可安装的 Python 版本（含 3.8+ 全系列，实时同步官方）
uv python list-available

• 输出包含：主版本（3.12/3.11）、小版本（3.12.7/3.11.9）、是否为稳定版等信息。

3.1.2 查看本地已安装的 Python 版本

# 列出 UV 管理的所有本地 Python 版本
uv python list

• 初始执行时仅显示「系统默认 Python」，安装后会新增 UV 管理的版本；
• 标注 (default) 为当前 UV 优先使用的版本。

3.2 安装指定版本 Python（以 3.12 为例，ComfyUI 推荐）

UV 支持指定主版本（自动安装最新稳定版）或指定精确小版本，命令简洁，无需额外配置。

3.2.1 安装 Python 3.12 最新稳定版（推荐）

# 安装 3.12 系列最新稳定版（如 3.12.7，自动适配系统架构）
uv python install 3.12

• 耗时：10-20 秒（仅下载预编译包，无编译，比 pyenv 快 5-10 倍）；
• 安装路径：~/.cache/uv/python/（用户目录，无权限问题）。

3.2.2 安装 Python 精确小版本（可选）

若需要固定版本（如 3.12.0），直接指定完整版本号即可：

# 安装 Python 3.12.0 精确版本
uv python install 3.12.0

# 其他版本示例（3.11.9/3.10.14）
uv python install 3.11.9

3.3 切换/设置默认 Python 版本

3.3.1 设置 UV 全局默认 Python 版本

将 UV 安装的 Python 3.12 设置为当前用户全局默认（不影响系统 Python，仅终端执行 python 时生效）：

# 将 3.12 设置为 UV 全局默认 Python 版本
uv python default 3.12

验证：新开终端执行 python --version，会显示 UV 安装的 3.12.x 版本。

3.3.2 查看当前 Python 版本路径

# 查看 UV 默认 Python 的安装路径
uv python which

# 查看指定版本 Python 的安装路径（如 3.12）
uv python which 3.12

3.4 卸载指定 Python 版本（可选）

若无需某个版本，可一键卸载，无文件残留：

# 卸载 Python 3.12 全系列
uv python uninstall 3.12

# 卸载精确小版本（如 3.12.0）
uv python uninstall 3.12.0

3.5 国内镜像加速（解决 Python 安装下载慢）

若安装 Python 时提示网络超时/下载卡顿，配置清华镜像源（永久生效），下载速度提升 10 倍以上：

# 配置 UV 的 Python 版本下载镜像（清华源，全局永久生效）
uv config set python.mirror_url "https://mirrors.tuna.tsinghua.edu.cn/python/"

配置后重新执行 uv python install 3.12 即可从国内源下载。

四、第三步：UV 创建并管理虚拟环境（指定 Python 版本）

UV 的 venv 子命令专门用于虚拟环境管理，毫秒级创建，支持显式指定 Python 版本，与 UV 安装的 Python 版本无缝关联，完美实现项目环境隔离。

4.1 核心原则

创建虚拟环境时必须显式指定 --python 版本，否则会默认使用系统 Python，失去版本隔离的意义（重点！）。

4.2 创建虚拟环境（以 ComfyUI 项目为例）

4.2.1 进入项目目录

首先切换到你的 ComfyUI 项目根目录（替换为实际路径）：

# 示例：ComfyUI 项目路径为 /workspace/ComfyUI
cd /workspace/ComfyUI

4.2.2 创建指定 Python 3.12 的虚拟环境

# 核心命令：创建虚拟环境，指定使用 UV 安装的 Python 3.12
# 默认环境名：venv（生成在项目根目录，可自定义）
uv venv --python 3.12

4.2.3 自定义虚拟环境名称（可选）

若不想使用默认的 venv，直接在命令后添加自定义名称即可：

# 创建名为 comfyui-venv 的虚拟环境，指定 Python 3.12
uv venv --python 3.12 comfyui-venv

• 虚拟环境文件夹会以自定义名称生成（如 comfyui-venv/），不影响其他操作。

4.3 激活虚拟环境

创建完成后，执行激活命令，激活后终端前缀会显示环境名（如 (venv)），此时所有 python/pip 操作均基于指定的 3.12 版本，与系统/其他项目完全隔离。

4.3.1 激活默认名称（venv）的虚拟环境

# Linux/Mac 通用激活命令
source venv/bin/activate

4.3.2 激活自定义名称的虚拟环境

# 示例：激活 comfyui-venv 环境
source comfyui-venv/bin/activate

4.4 验证虚拟环境的 Python 版本（必做）

激活后执行以下命令，确认 Python 版本为 3.12.x，确保环境配置正确：

# 检查 Python 版本（必为 3.12.x）
python --version

# 检查 pip 版本（自动关联 3.12 的 pip，无版本冲突）
pip --version

成功输出示例

Python 3.12.7
pip 24.2 from /workspace/ComfyUI/venv/lib/python3.12/site-packages/pip (python 3.12)

4.5 退出虚拟环境

任意目录执行以下命令，即可退出虚拟环境，终端前缀恢复正常：

# 全局退出命令，无参数
deactivate

4.6 删除虚拟环境（可选）

若无需某个虚拟环境，直接删除项目目录下的虚拟环境文件夹即可，无任何残留文件：

# 删除默认的 venv 环境
rm -rf venv

# 删除自定义的 comfyui-venv 环境
rm -rf comfyui-venv

五、第四步：虚拟环境内的依赖管理（UV 替代 pip，速度拉满）

激活虚拟环境后，UV 可直接替代 pip 进行依赖安装/升级/冻结，兼容所有 pip 命令和 requirements.txt 文件，且速度远超原生 pip（基于 Rust 实现多线程下载）。

5.1 核心优势

1. 兼容 pip 所有参数，无需修改使用习惯；
2. 依赖缓存复用，相同包无需重复下载；
3. 自动解决依赖冲突，比 pip 更智能；
4. 支持国内镜像源，下载速度极快。

5.2 基础依赖操作（激活环境后执行）

5.2.1 升级虚拟环境内的 pip（可选，推荐）

# UV 替代 pip 升级，速度更快
uv pip install --upgrade pip

5.2.2 安装项目依赖（从 requirements.txt 安装，ComfyUI 核心）

ComfyUI 项目根目录包含 requirements.txt，直接执行以下命令即可一键安装所有依赖：

# 从 requirements.txt 安装所有依赖，兼容 pip 语法
uv pip install -r requirements.txt

• 耗时：比原生 pip install -r requirements.txt 快 5-20 倍，尤其适合依赖较多的项目。

5.2.3 单独安装指定依赖（替代 pip install）

# 示例：安装 torch/torchvision（ComfyUI 常用依赖）
uv pip install torch torchvision

# 安装指定版本依赖
uv pip install requests==2.31.0

5.2.4 卸载依赖（替代 pip uninstall）

# 卸载单个依赖
uv pip uninstall requests -y

# 卸载多个依赖
uv pip uninstall torch torchvision -y

5.2.5 冻结项目依赖（生成/更新 requirements.txt）

若在项目中新增了依赖，执行以下命令冻结当前环境的所有依赖版本，更新到 requirements.txt：

# 冻结依赖并覆盖到 requirements.txt
uv pip freeze > requirements.txt

5.3 配置 pip 国内镜像源（解决依赖下载慢）

配置清华源作为 UV pip 的默认镜像，永久生效，后续所有依赖安装均从国内源下载：

# 配置 UV pip 的默认镜像源（清华源，全局永久生效）
uv config set pip.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"

六、第五步：ComfyUI 项目完整实操流程（UV 版）

整合以上所有步骤，为 ComfyUI 项目快速配置 Python 3.12 + 独立虚拟环境 + 依赖安装，命令可直接复制按顺序执行，全程 5 分钟内完成：

# =============================================
# 1. 安装 UV 工具（一键执行）
# =============================================
curl -LsSf https://astral.sh/uv/install.sh | sh
# 重启终端后验证 UV 安装
uv --version

# =============================================
# 2. 配置国内镜像（解决下载慢，可选但推荐）
# =============================================
uv config set python.mirror_url "https://mirrors.tuna.tsinghua.edu.cn/python/"
uv config set pip.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"

# =============================================
# 3. 安装 Python 3.12 最新稳定版
# =============================================
uv python install 3.12

# =============================================
# 4. 进入 ComfyUI 项目根目录（替换为你的实际路径）
# =============================================
cd /workspace/ComfyUI

# =============================================
# 5. 创建 Python 3.12 专属虚拟环境
# =============================================
uv venv --python 3.12

# =============================================
# 6. 激活虚拟环境
# =============================================
source venv/bin/activate

# =============================================
# 7. 验证 Python 版本（确保为 3.12.x）
# =============================================
python --version
pip --version

# =============================================
# 8. 安装 ComfyUI 所有依赖（速度拉满）
# =============================================
uv pip install -r requirements.txt

# =============================================
# 9. 运行 ComfyUI（激活环境后直接执行）
# =============================================
python main.py

七、UV 常用核心命令速查（收藏备用）

整理所有高频操作命令，按功能分类，方便快速查阅：

7.1 UV 基础命令

7.2 Python 版本管理命令

7.3 虚拟环境管理命令

7.4 依赖管理命令（激活环境后执行）

八、常见问题及解决方案

8.1 执行 UV 命令提示「command not found」

• 原因：环境变量未生效，或安装后未重启终端；
• 解决方案：
  1. 重启终端（推荐，最简单）；
  2. 手动刷新环境变量：source ~/.bashrc（bash）或 source ~/.zshrc（zsh）。

8.2 安装 Python 时提示「网络超时/下载失败」

• 原因：默认下载源为国外，网络波动；
• 解决方案：配置清华 Python 镜像源，执行：
  Copy

  uv config set python.mirror_url "https://mirrors.tuna.tsinghua.edu.cn/python/"
  

  配置后重新执行 uv python install 3.12。

8.3 创建虚拟环境时提示「Python 3.12 未找到」

• 原因：未先安装 Python 3.12，或版本号输入错误；
• 解决方案：
  1. 先执行 uv python install 3.12 安装版本；
  2. 验证安装成功：uv python list（确认包含 3.12 版本）；
  3. 重新执行创建虚拟环境命令。

8.4 激活虚拟环境后 Python 版本不是 3.12

• 原因：创建虚拟环境时未指定 --python 3.12，默认使用了系统 Python；
• 解决方案：
  1. 退出虚拟环境：deactivate；
  2. 删除原有虚拟环境：rm -rf venv；
  3. 重新创建并指定版本：uv venv --python 3.12；
  4. 重新激活并验证版本。

8.5 安装 ComfyUI 依赖时提示「权限不足」

• 原因：未激活虚拟环境，试图安装到系统 Python 目录（需 sudo）；
• 解决方案：
  1. 进入 ComfyUI 目录，激活虚拟环境：source venv/bin/activate；
  2. 重新执行依赖安装命令：uv pip install -r requirements.txt（无需 sudo）。

8.6 UV pip 安装依赖时提示「找不到包」

• 原因：pip 镜像源配置错误，或包名输入错误；
• 解决方案：
  1. 检查镜像源配置：uv config get pip.index-url（确认是清华源/阿里云源）；
  2. 重新配置正确的 pip 镜像源：
     Copy

     uv config set pip.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"
     

  3. 确认包名拼写正确（与 PyPI 一致）。

九、UV 与传统工具（pyenv/venv/pip）对比