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

1. 初始化项目 A

   cd project_a
   uv python pin 3.11.5    # 锁定 Python 版本
   uv venv                 # 创建虚拟环境
   uv add numpy            # 添加依赖
   uv sync
   

2. 初始化项目 B

   cd project_b
   uv python pin 3.12.0    # 锁定 Python 版本
   uv venv
   uv add pandas
   uv sync
   

3. 运行脚本

   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>	自动激活虚拟环境并执行

---

六、注意事项

1. 全局 Python 版本
   uv 默认通过虚拟环境隔离 Python 版本，无需全局切换。每个项目独立管理版本。

2. 依赖锁定文件
   提交 uv.lock 到版本控制，确保团队成员和 CI/CD 环境的一致性。

3. 性能优化
   利用 uv 的全局缓存加速依赖安装（默认路径：~/.cache/uv）。

通过上述操作，uv 可实现从 Python 版本管理到依赖同步的全流程高效控制。