使用uv安装Python项目开发依赖的指南

问题陈述

在使用现代开发工具管理Python项目时，常常需要区分生产环境和开发环境的依赖项。当尝试使用uv（一个高效的Python依赖管理工具）时，开发者常遇到如何正确安装所有开发依赖（dev-dependencies） 的问题。具体表现为：

• uv sync无法安装pyproject.toml中定义的开发依赖
• 运行命令时出现布局错误如：Multiple top-level packages discovered in a flat-layout
• 无法找到统一的方法为开发环境安装所有必需依赖

解决方案

1. 依赖组(Dependency Groups)机制

uv使用PEP 735提出的依赖组概念管理开发依赖。标准配置如下：

[project]
name = "my-project"
dependencies = ["django"]

[dependency-groups]
dev = ["factory-boy", "pytest"]

关键区别： 开发依赖必须置于[dependency-groups]而非[tool.uv]下

2. 添加开发依赖的命令

使用uv add命令添加开发依赖项至dev组：

uv add --dev factory-boy  # 简写形式
# 等价于
uv add --group dev factory-boy

3. 安装全部依赖（含开发依赖）

只需执行uv sync命令，它会默认安装所有dev组依赖：

uv venv --python 3.10  # 创建虚拟环境
uv sync                # 安装所有依赖（含开发依赖）

激活环境验证安装：

source .venv/bin/activate
pip list | grep factory-boy

4. 安装特定依赖组

可选择只安装特定组的依赖（如测试组）：

uv add --group test pytest
uv sync --group test

高级配置

配置默认依赖组

修改pyproject.toml自定义默认安装的依赖组：

[tool.uv]
default-groups = ["dev", "test"]  # 默认会安装dev和test组

排除开发依赖

使用--no-dev排除开发依赖，仅安装生产依赖：

uv sync --no-dev  # 仅安装生产环境依赖

固定Python版本

使用.python-version文件固定项目Python版本：

uv python pin 3.10  # 生成.python-version文件

常见问题解决

处理布局错误

若运行uv sync时出现布局错误：

error: Multiple top-level packages discovered in a flat-layout

添加以下配置到pyproject.toml：

[tool.setuptools]
py-modules = []

工作流推荐

1. 初始化项目：

   uv init

2. 添加依赖：

   uv add django         # 生产依赖
   uv add --dev pytest   # 开发依赖

3. 同步环境：

   uv sync  # 一键安装所有依赖

总结

uv通过依赖组机制优雅地管理开发依赖：

1. 生产依赖声明在[project]部分
2. 开发依赖声明在[dependency-groups]部分
3. uv sync默认安装所有依赖（含dev组）
4. 使用--no-dev选项排除开发依赖

最佳实践提示： 始终使用uv add --dev命令添加开发依赖，它将自动更新pyproject.toml的依赖组配置，避免手动编辑错误。