使用 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 执行安装命令
```bash
# 全局安装 UV（自动适配系统架构，Linux/Mac/Windows 通用）
curl -LsSf https://astral.sh/uv/install.sh | sh
```
- 安装过程：自动下载对应系统的 UV 二进制文件，配置到用户环境变量（`~/.cargo/bin` 或 `~/.local/bin`）；
- 耗时：10 秒内完成，无编译过程。

### 2.2 验证安装成功
安装完成后**重启终端**（让环境变量生效），执行以下命令验证：
```bash
# 查看 UV 版本，输出版本信息即安装成功
uv --version
```
#### 成功输出示例
```
uv 0.4.17 (a1b2c3d 2026-02-03)
```

### 2.3 解决「command not found」报错
若重启终端后仍提示 `uv: command not found`，手动刷新环境变量即可：
```bash
# 适用于 bash 终端（Debian/Ubuntu 默认）
source ~/.bashrc

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

## 三、第二步：UV 管理 Python 版本（核心操作）
UV 内置 `python` 子命令，支持**一键安装/卸载/切换/查看**任意 Python 版本，直接下载官方预编译包，无需处理编译依赖，全程秒级完成。

### 3.1 核心命令：查看可安装/已安装的 Python 版本
#### 3.1.1 查看 UV 支持安装的所有 Python 版本
```bash
# 列出所有可安装的 Python 版本（含 3.8+ 全系列，实时同步官方）
uv python list-available
```
- 输出包含：主版本（3.12/3.11）、小版本（3.12.7/3.11.9）、是否为稳定版等信息。

#### 3.1.2 查看本地已安装的 Python 版本
```bash
# 列出 UV 管理的所有本地 Python 版本
uv python list
```
- 初始执行时仅显示「系统默认 Python」，安装后会新增 UV 管理的版本；
- 标注 `(default)` 为当前 UV 优先使用的版本。

### 3.2 安装指定版本 Python（以 3.12 为例，ComfyUI 推荐）
UV 支持**指定主版本**（自动安装最新稳定版）或**指定精确小版本**，命令简洁，无需额外配置。

#### 3.2.1 安装 Python 3.12 最新稳定版（推荐）
```bash
# 安装 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），直接指定完整版本号即可：
```bash
# 安装 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` 时生效）：
```bash
# 将 3.12 设置为 UV 全局默认 Python 版本
uv python default 3.12
```
验证：新开终端执行 `python --version`，会显示 UV 安装的 3.12.x 版本。

#### 3.3.2 查看当前 Python 版本路径
```bash
# 查看 UV 默认 Python 的安装路径
uv python which

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

### 3.4 卸载指定 Python 版本（可选）
若无需某个版本，可一键卸载，无文件残留：
```bash
# 卸载 Python 3.12 全系列
uv python uninstall 3.12

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

### 3.5 国内镜像加速（解决 Python 安装下载慢）
若安装 Python 时提示**网络超时/下载卡顿**，配置清华镜像源（永久生效），下载速度提升 10 倍以上：
```bash
# 配置 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 项目根目录（替换为实际路径）：
```bash
# 示例：ComfyUI 项目路径为 /workspace/ComfyUI
cd /workspace/ComfyUI
```

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

#### 4.2.3 自定义虚拟环境名称（可选）
若不想使用默认的 `venv`，直接在命令后添加自定义名称即可：
```bash
# 创建名为 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）的虚拟环境
```bash
# Linux/Mac 通用激活命令
source venv/bin/activate
```

#### 4.3.2 激活自定义名称的虚拟环境
```bash
# 示例：激活 comfyui-venv 环境
source comfyui-venv/bin/activate
```

### 4.4 验证虚拟环境的 Python 版本（必做）
激活后执行以下命令，确认 Python 版本为 3.12.x，确保环境配置正确：
```bash
# 检查 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 退出虚拟环境
任意目录执行以下命令，即可退出虚拟环境，终端前缀恢复正常：
```bash
# 全局退出命令，无参数
deactivate
```

### 4.6 删除虚拟环境（可选）
若无需某个虚拟环境，直接删除项目目录下的虚拟环境文件夹即可，**无任何残留文件**：
```bash
# 删除默认的 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（可选，推荐）
```bash
# UV 替代 pip 升级，速度更快
uv pip install --upgrade pip
```

#### 5.2.2 安装项目依赖（从 requirements.txt 安装，ComfyUI 核心）
ComfyUI 项目根目录包含 `requirements.txt`，直接执行以下命令即可一键安装所有依赖：
```bash
# 从 requirements.txt 安装所有依赖，兼容 pip 语法
uv pip install -r requirements.txt
```
- 耗时：比原生 `pip install -r requirements.txt` 快 5-20 倍，尤其适合依赖较多的项目。

#### 5.2.3 单独安装指定依赖（替代 pip install）
```bash
# 示例：安装 torch/torchvision（ComfyUI 常用依赖）
uv pip install torch torchvision

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

#### 5.2.4 卸载依赖（替代 pip uninstall）
```bash
# 卸载单个依赖
uv pip uninstall requests -y

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

#### 5.2.5 冻结项目依赖（生成/更新 requirements.txt）
若在项目中新增了依赖，执行以下命令冻结当前环境的所有依赖版本，更新到 `requirements.txt`：
```bash
# 冻结依赖并覆盖到 requirements.txt
uv pip freeze > requirements.txt
```

### 5.3 配置 pip 国内镜像源（解决依赖下载慢）
配置清华源作为 UV pip 的默认镜像，永久生效，后续所有依赖安装均从国内源下载：
```bash
# 配置 UV pip 的默认镜像源（清华源，全局永久生效）
uv config set pip.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"
```

## 六、第五步：ComfyUI 项目完整实操流程（UV 版）
整合以上所有步骤，为 ComfyUI 项目快速配置 **Python 3.12 + 独立虚拟环境 + 依赖安装**，**命令可直接复制按顺序执行**，全程 5 分钟内完成：

```bash
# =============================================
# 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 基础命令
| 功能         | 命令                                          |
|--------------|-----------------------------------------------|
| 安装 UV      | `curl -LsSf https://astral.sh/uv/install.sh | sh` |
| 查看 UV 版本 | `uv --version`                                 |
| 查看 UV 帮助 | `uv --help`                                    |

### 7.2 Python 版本管理命令
| 功能                     | 命令                                          |
|--------------------------|-----------------------------------------------|
| 查看可安装 Python 版本   | `uv python list-available`                    |
| 查看已安装 Python 版本   | `uv python list`                              |
| 安装 Python 3.12         | `uv python install 3.12`                      |
| 安装精确版本 3.12.0      | `uv python install 3.12.0`                    |
| 设置全局默认 Python 3.12 | `uv python default 3.12`                      |
| 查看 Python 安装路径     | `uv python which 3.12`                        |
| 卸载 Python 3.12         | `uv python uninstall 3.12`                    |
| 配置 Python 镜像源       | `uv config set python.mirror_url "清华源地址"` |

### 7.3 虚拟环境管理命令
| 功能                     | 命令（项目目录执行）|
|--------------------------|-----------------------------------------------|
| 创建 Python 3.12 虚拟环境 | `uv venv --python 3.12`                       |
| 自定义名称创建环境       | `uv venv --python 3.12 自定义名称`            |
| 激活默认环境             | `source venv/bin/activate`                    |
| 激活自定义环境           | `source 自定义名称/bin/activate`              |
| 退出虚拟环境             | `deactivate`                                  |
| 删除虚拟环境             | `rm -rf 环境名`（如 rm -rf venv）|

### 7.4 依赖管理命令（激活环境后执行）
| 功能                     | 命令                                          |
|--------------------------|-----------------------------------------------|
| 升级 pip                 | `uv pip install --upgrade pip`                |
| 安装项目依赖             | `uv pip install -r requirements.txt`          |
| 安装指定依赖             | `uv pip install 包名==版本号`                 |
| 卸载依赖                 | `uv pip uninstall 包名 -y`                    |
| 冻结依赖到 requirements.txt | `uv pip freeze > requirements.txt`          |
| 配置 pip 镜像源          | `uv config set pip.index-url "清华源地址"`     |

## 八、常见问题及解决方案
### 8.1 执行 UV 命令提示「command not found」
- **原因**：环境变量未生效，或安装后未重启终端；
- **解决方案**：
  1. 重启终端（推荐，最简单）；
  2. 手动刷新环境变量：`source ~/.bashrc`（bash）或 `source ~/.zshrc`（zsh）。

### 8.2 安装 Python 时提示「网络超时/下载失败」
- **原因**：默认下载源为国外，网络波动；
- **解决方案**：配置清华 Python 镜像源，执行：
  ```bash
  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 镜像源：
     ```bash
     uv config set pip.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"
     ```
  3. 确认包名拼写正确（与 PyPI 一致）。

## 九、UV 与传统工具（pyenv/venv/pip）对比
| 功能/工具                | UV                          | pyenv + venv + pip          | 系统 apt 安装              |
|--------------------------|-----------------------------|-----------------------------|---------------------------|
| Python 安装方式          | 预编译包（秒级，无编译）| 轻量编译（1-2 分钟）| 系统预编译包（30 秒）|
| 虚拟环境创建速度         | 毫秒级                      | 秒级                        | 秒级                      |
| 依赖安装速度             | 极快（Rust 多线程）| 一般（原生 pip 单线程）| 一般（原生 pip 单线程）|
| 工具依赖                 | 无（单文件安装）| 需安装 git/编译依赖         | 需清理系统源/处理冲突     |
| Python 版本隔离性        | 完全隔离（用户目录）| 完全隔离（用户目录）| 与系统 Python 共存        |
| 操作复杂度               | 一站式（单工具）| 多工具配合（需切换/初始化） | 需手动指定版本（python3.12） |
| 跨平台兼容性