uv 安装多版本 Python 及虚拟环境使用指南（替代 pyenv + pip）

在项目目录下初始化虚拟环境非常简单：

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 可以大幅减少环境配置的复杂度。

九、常见问题

IDE 找不到解释器

如果 VS Code 或 PyCharm 无法自动识别虚拟环境，请手动指向以下路径：

项目目录/.venv/bin/python

创建失败

若 uv venv 报错，请先确认目标 Python 版本是否已安装：

uv python list --installed

系统缺少 Python 3.12？

不用担心，uv 会从官方源拉取预编译的二进制包，不依赖系统仓库中的 Python 版本。

十、结语

uv 代表了 Python 工具链的未来方向，它将原本分散的工具整合成了一个高效的整体。虽然迁移成本极低，但对于新启动的项目，强烈建议直接采用 uv 来管理环境和依赖，告别繁琐的 pyenv 配置。