使用 UV 管理 Python 版本、虚拟环境及项目依赖(Debian/Ubuntu 详细教程) 本文共有11918个字,关键词: 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) | | 跨平台兼容性 「一键投喂 软糖/蛋糕/布丁/牛奶/冰阔乐!」 赞赏 × 梦白沙 (๑>ڡ<)☆谢谢老板~ 1元 2元 5元 10元 50元 任意金额 2元 使用微信扫描二维码完成支付 版权声明:本文为作者原创,如需转载须联系作者本人同意,未经作者本人同意不得擅自转载。 随手发现,Python 2026-02-03 评论 9 次浏览