uv 安装多版本 Python 及虚拟环境使用指南
适用系统：Ubuntu / Linux / macOS / Windows 测试环境：Ubuntu 20.04, Python 3.8 ~ 3.13
一、为什么选择 uv？
uv 是 Astral（ruff 作者团队）推出的新一代 Python 工具，核心目标是统一并简化现有的 Python 开发流程。
简单来说，它试图整合 pyenv、venv 和 pip 的功能，同时利用 Rust 带来显著的性能提升。对于追求效率的开发者来说，这意味着更少的依赖配置和更快的执行速度。
核心优势
- 极速：基于 Rust 编写，安装和运行速度远超传统工具。
- 统一管理：支持在同一机器上安装和管理多个 Python 版本，互不干扰。
- 全功能替代：内置虚拟环境管理，完全兼容
pip命令。 - 轻量级：单一二进制文件，无需复杂的环境依赖。
- IDE 友好：与 VS Code、PyCharm 等主流编辑器完美集成。
二、安装 uv
方式一：官方脚本（推荐）
这是最快捷的方式，适用于大多数 Linux 和 macOS 用户。
curl -LsSf https://astral.sh/uv/install.sh | sh
安装完成后，记得刷新环境变量：
source ~/.bashrc
验证安装是否成功：
uv --version
方式二：Cargo 安装
如果你已经安装了 Rust，也可以通过 Cargo 直接安装，但通常不如官方脚本方便。
cargo install uv
三、管理 Python 版本
查看可用版本
在安装之前，我们可以先看看有哪些版本可供下载：
uv python list
输出示例：
3.8.18 3.9.19 3.10.14 3.11.9 3.12.3 3.13.0
安装指定版本
你可以按需安装特定版本，甚至一次性安装多个版本共存。
# 安装 Python 3.12
uv python install 3.12
# 批量安装多个版本
uv python install 3.10 3.11 3.13
⚠️ 注意：uv 安装的 Python 版本独立于系统自带版本，不会覆盖系统环境。
查看已安装版本
uv python list --installed
默认存储路径通常在 ~/.local/share/uv/python/，每个版本都有独立的目录结构。
四、创建与管理虚拟环境
创建虚拟环境
在项目目录下初始化虚拟环境非常简单：
cd your_project
uv venv
默认情况下，它会使用最新安装的 Python 版本，并在当前目录生成 .venv 文件夹。
指定 Python 版本
为了保持项目一致性，建议显式指定 Python 版本：
# 使用 Python 3.12
uv venv --python=3.12 .venv
# 使用 Python 3.10
uv venv --python=3.10 .venv
📌 建议：统一使用 .venv 作为虚拟环境目录名，便于团队协作识别。
激活与退出
# 激活环境
source .venv/bin/activate
# 激活后提示符会显示 (.venv)
# 退出环境
deprecate
五、包管理：替代 pip
uv 提供了与原生命令高度兼容的包管理接口，速度更快。
安装依赖
uv pip install requests flask
从 requirements.txt 安装
uv pip install -r requirements.txt
查看与导出
# 查看已安装包
uv pip list
# 导出为 requirements.txt
uv pip freeze > requirements.txt
六、标准项目工作流示例
下面是一个从零开始搭建项目的完整流程，供参考：
# 1. 创建项目目录
mkdir my_project
cd my_project
# 2. 创建 Python 3.12 虚拟环境
uv venv --python=3.12 .venv
# 3. 激活环境
source .venv/bin/activate
# 4. 安装核心依赖
uv pip install fastapi uvicorn
# 5. 运行程序
python main.py
七、高级用法
不激活环境直接运行脚本
有时候我们不想手动激活环境，可以直接用 uv run 执行：
# 使用默认环境
uv run python script.py
# 指定 Python 版本
uv run --python=3.12 python script.py
uvx：临时运行工具
uvx 允许你临时运行任何 Python 工具，无需预先安装到环境中，非常适合 CI 或一次性任务。
uvx black .
uvx ruff check .
uvx pytest
特点包括：不污染环境、用完即走、适合本地格式化检查。
八、对比总结
| 功能 | uv | pyenv | venv |
|---|---|---|---|
| 安装 Python | ✅ | ✅ | ❌ |
| 虚拟环境 | ✅ | ❌ | ✅ |
| pip 管理 | ✅ | ❌ | ❌ |
| 速度 | 🚀🚀🚀 | 慢 | 中 |
| 单工具 | ✅ | ❌ | ❌ |
对于新项目，直接使用 uv 可以大幅减少环境配置的复杂度。
九、常见问题
IDE 找不到解释器
如果 VS Code 或 PyCharm 无法自动识别虚拟环境，请手动指向以下路径：
项目目录/.venv/bin/python
创建失败
若 uv venv 报错，请先确认目标 Python 版本是否已安装：
uv python list --installed
系统缺少 Python 3.12？
不用担心，uv 会从官方源拉取预编译的二进制包，不依赖系统仓库中的 Python 版本。
十、结语
uv 代表了 Python 工具链的未来方向，它将原本分散的工具整合成了一个高效的整体。虽然迁移成本极低，但对于新启动的项目，强烈建议直接采用 uv 来管理环境和依赖，告别繁琐的 pyenv 配置。
