Python 包管理工具uv常用场景使用指南
一、Python 版本管理
1. 查看已安装的 Python 版本
uv python list
- 输出示例：
Installed Python versions: - 3.11.5 (default) - 3.12.0
2. 安装指定 Python 版本
uv python install 3.12.0 # 安装 Python 3.12.0
- 支持安装任意版本（如
3.9.18、3.13.0等）。 - 安装完成后，通过
uv python list验证是否成功。
3. 切换项目 Python 版本
uv python pin 3.12.0 # 将当前项目锁定到 Python 3.12.0
- 此命令会在项目根目录生成
.python-version文件，记录版本信息。 - 后续所有操作（如创建虚拟环境、运行脚本）均默认使用此版本。
二、虚拟环境管理
1. 创建虚拟环境并指定 Python 版本
uv venv --python 3.12.0 # 创建名为 .venv 的虚拟环境，使用 Python 3.12.0
- 若未指定
--python，默认使用项目锁定的版本（通过uv python pin设置）。
2. 激活虚拟环境
# Linux/macOS
source .venv/bin/activate# Windows
.venv\Scripts\activate
- uv 推荐直接使用
uv run命令运行脚本，无需手动激活环境：uv run script.py # 自动激活虚拟环境并执行脚本
三、依赖管理
1. 同步依赖项
在项目根目录运行以下命令，根据 pyproject.toml 或 requirements.txt 安装依赖：
uv sync # 安装所有依赖并生成/更新 uv.lock 文件
- 按分组安装依赖：
uv sync --only prod # 仅安装生产依赖 uv sync --only dev # 仅安装开发依赖
2. 添加新依赖并同步
uv add requests==2.31.0 # 添加生产依赖
uv add --group dev pytest # 添加开发依赖
uv sync # 更新依赖并生成锁定文件
四、多版本 Python 场景示例
场景：项目 A 使用 Python 3.11，项目 B 使用 Python 3.12
-
初始化项目 A
cd project_a uv python pin 3.11.5 # 锁定 Python 版本 uv venv # 创建虚拟环境 uv add numpy # 添加依赖 uv sync -
初始化项目 B
cd project_b uv python pin 3.12.0 # 锁定 Python 版本 uv venv uv add pandas uv sync -
运行脚本
cd project_a uv run main.py # 使用 Python 3.11 和 project_a 的依赖cd ../project_b uv run main.py # 使用 Python 3.12 和 project_b 的依赖
五、常用命令总结
| 功能 | 命令 | 说明 |
|---|---|---|
| 安装 Python 版本 | uv python install <version> | 如 uv python install 3.12.0 |
| 锁定项目 Python 版本 | uv python pin <version> | 生成 .python-version 文件 |
| 创建虚拟环境 | uv venv | 默认使用锁定的 Python 版本 |
| 同步依赖 | uv sync | 安装依赖并生成/更新 uv.lock |
| 运行脚本 | uv run <script> | 自动激活虚拟环境并执行 |
六、注意事项
-
全局 Python 版本
uv默认通过虚拟环境隔离 Python 版本，无需全局切换。每个项目独立管理版本。 -
依赖锁定文件
提交uv.lock到版本控制，确保团队成员和 CI/CD 环境的一致性。 -
性能优化
利用uv的全局缓存加速依赖安装（默认路径：~/.cache/uv）。
通过上述操作，uv 可实现从 Python 版本管理到依赖同步的全流程高效控制。