5 分钟上手 uv：Python 依赖管理最佳实践

通过 uv （Python 新一代极速依赖管理工具）维护构建 venv 环境，核心优势是「快速创建环境 + 自动解析 pyproject.toml 依赖」，无需手动区分 Poetry/Pip 配置，步骤更简洁。

一、完整操作步骤

安装 uv（首次使用需执行）

# Mac/Linux（终端直接执行）
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows（PowerShell，需管理员权限）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 或通过 pip 安装（兼容所有系统，较慢）
pip install uv

✅ 验证安装：执行 uv --version，输出版本号即成功。

清理旧环境（可选但推荐）

若当前目录已有旧 venv 环境（如 .venv），先删除避免冲突（uv 后续创建新环境会覆盖，但清理更干净）：

# Mac/Linux/Git Bash（Windows）rm -rf .venv

# Windows CMD
rd /s /q .venv

# Windows PowerShell
Remove-Item -Recurse -Force .venv

创建并激活新的 venv 环境

uv 自带 venv 管理功能，无需手动用 python -m venv，直接一步创建：

# 步骤 1：在项目根目录（pyproject.toml 所在目录）创建 .venv 环境
uv venv .venv  # .venv 是环境文件夹名，可自定义（如 venv）

✅ 说明：uv 会自动使用当前系统默认的 Python 版本创建环境（若需指定版本，可加 --python 3.11 参数，如 uv venv .venv --python 3.11）。

激活虚拟环境

激活命令与原生 venv 完全一致（终端前缀显示 (.venv) 即成功）：

系统 / 终端	激活命令
Mac/Linux/bash	source .venv/bin/activate
Mac/Linux/zsh	source .venv/bin/activate
Windows CMD	.venv\Scripts\activate.bat
Windows PowerShell	.venv\Scripts\Activate.ps1（权限问题参考之前：执行 Set-ExecutionPolicy RemoteSigned）

基于 pyproject.toml 安装依赖

激活环境后，uv 会自动关联环境内的 Python/Pip，直接执行以下命令即可解析 pyproject.toml 并安装所有依赖：

uv sync 

✅ 关键特性：

• uv 会自动识别 pyproject.toml 的依赖格式（Poetry/Pip），无需额外配置；
• 若存在 poetry.lock 或 uv.lock（uv 生成的锁定文件），会优先按锁定版本安装，避免依赖漂移；
• 安装速度比 Pip/Poetry 快 10-100 倍（尤其依赖较多时）。

验证环境重建成功

uv pip list

二、安装依赖

1. 安装「生产依赖」（项目运行必需，同步到核心依赖组）

生产依赖指项目上线后仍需的包（如 requests、numpy），命令：

# 基础用法：安装最新稳定版，自动同步到 pyproject.toml
uv add 包名  # 例：uv add requests# 指定版本安装（推荐，避免依赖漂移）
uv add 包名==版本号  # 例：uv add requests==2.32.3（精确版本）
uv add 包名>=最低版本,<最高版本  # 例：uv add requests>=2.30.0,<3.0.0（版本区间）# 从特定源安装（如国内镜像，加速下载）
uv add 包名 --index-url https://pypi.tuna.tsinghua.edu.cn/simple  # 清华源示例

2. 安装「开发依赖」（仅开发时使用，同步到开发依赖组）

开发依赖指本地开发 / 测试所需的包（如 pytest、flake8、black），命令：

# 基础用法：--dev 标记为开发依赖
uv add --dev 包名  # 例：uv add --dev pytest# 指定版本安装开发依赖
uv add --dev pytest==7.4.4

3. 安装「可选依赖组」（按需启用，同步到对应依赖组）

若项目有可选依赖组（如 docs 文档依赖、test 测试依赖），命令：

# 安装到指定可选依赖组（需先在 pyproject.toml 定义组，或 uv 自动创建）
uv add 包名 --group 组名  # 例：uv add sphinx --group docs（文档依赖组）

三、关键注意事项

1. Python 版本匹配：

   1. uv 会默认使用执行 uv venv 时的 Python 版本（可通过 which python 查看）；
   2. 若 pyproject.toml 中指定了 Python 版本约束（如 requires-python = ">=3.10"），uv 会自动校验，不匹配则报错，需通过 uv venv --python 3.10 指定对应版本。

2. 锁定文件优化：

   1. 执行 uv install 后，会自动生成 uv.lock 文件（比 poetry.lock 更小、解析更快），建议提交到 Git 仓库，确保团队成员安装一致版本。
   2. 若项目原本用 Poetry，poetry.lock 仍可被 uv 识别，无需手动删除。

3. 开发依赖安装：

   1. 若 pyproject.toml 中用 Poetry 定义了 [tool.poetry.group.dev.dependencies]，或用 Pip 定义了 [project.optional-dependencies.dev]，uv install 会自动安装（无需额外参数）；
   2. 若需单独安装生产依赖（排除开发依赖），执行 uv install --only main。

4. 缓存清理（安装失败时） ：若依赖安装失败（如网络问题、包损坏），清理 uv 缓存后重试：

uv cache clean  # 一键清理所有缓存