管理依赖

• project.dependencies：已发布的依赖项。

• project.optional-dependenies：已经发布的可选依赖项。

• dependency-groups：用于开发的本地依赖项。

• tool.uv.sources：开发期间依赖项的备用源。

添加依赖

uv add httpx

可以使用 —dev、–group、–optional 将依赖项添加到备用字段。

在 requirements.txt 文件中声明的依赖可以使用 -r 选项添加到项目中。

uv add -r requirements.txt

删除依赖

uv remove httpx

可以使用 --dev、--group 或 --optional 标志从特定表中删除依赖项。

如果为已删除的依赖项定义了源，并且没有其他对该依赖项的引用，则该源也将被删除。

更改依赖

要更改现有依赖项，例如，为 httpx 使用不同的约束：

uv add "httpx>0.1.0"

说明

在此示例中，我们正在更改 pyproject.toml 中依赖项的约束。只有在满足新约束所必需时，依赖项的锁定版本才会更改。要强制包版本更新到约束内的最新版本，请使用 --upgrade-package <name>，例如：

uv add "httpx>0.1.0" --upgrade-package httpx

请求不同的依赖源将更新 tool.uv.sources 表，例如，在开发期间使用本地路径中的 httpx：

uv add "httpx @ ../httpx"

可选依赖

作为库发布的项目通常会将某些功能设为可选，以减少默认依赖树。例如，Pandas 有一个 excel 和一个 plot，以避免安装 Excel 解析器和 matplotlib，除非有人明确要求它们。Extras 使用 package[<extra>] 语法请求，例如 pandas[plot, excel]。

可选依赖项在 [project.optional-dependencies] 中指定，这是一个 TOML 表，它将 extra 名称映射到其依赖项，

可选依赖项可以像普通依赖项一样在 tool.uv.sources 中有条目。

[project]
name = "pandas"
version = "1.0.0"

[project.optional-dependencies]
plot = [
  "matplotlib>=3.6.3"
]
excel = [
  "odfpy>=1.4.1",
  "openpyxl>=3.1.0",
  "python-calamine>=0.1.7",
  "pyxlsb>=1.0.10",
  "xlrd>=2.0.1",
  "xlsxwriter>=3.0.5"
]

# 添加可选依赖
uv add httpx --optional network

开发依赖

开发依赖项是仅限本地的，在发布到 PyPI 或其他索引时，不会包含在项目需求中。因此，开发依赖项不包含在 [project] 表中。

开发依赖项可以像普通依赖项一样在 tool.uv.sources 中有条目。

uv add --dev pytest

uv 使用 [dependency-groups] 表（在 PEP 735 中定义）来声明开发依赖项。上述命令将创建一个 dev 组：

[dependency-groups]
dev = [
  "pytest >=8.1.1,<9"
]

dev 组是特殊情况；有 --dev、--only-dev 和 --no-dev 标志来切换其依赖项的包含或排除。请改用 --no-default-groups 来禁用所有默认组。此外，dev 组默认同步。

依赖组

开发依赖项可以使用 --group 标志分为多个组。

例如，要在 lint 组中添加开发依赖项：

uv add --group lint ruff

[dependency-groups]
dev = [
  "pytest"
]
lint = [
  "ruff"
]

定义组后，可以使用 --all-groups、--no-default-groups、--group、--only-group 和 --no-group 选项来包含或排除其依赖项。

tip

--dev、--only-dev 和 --no-dev 标志分别等效于 --group dev、--only-group dev 和 --no-group dev。

uv 要求所有依赖组彼此兼容，并在创建锁文件时一起解析所有组。

如果一个组中声明的依赖项与另一个组中的依赖项不兼容，uv 将无法解析项目的需求并出现错误。

默认组

默认情况下，uv 在环境中包含 dev 依赖组（例如，在 uv run 或 uv sync 期间）。可以使用 tool.uv.default-groups 设置更改要包含的默认组。

[tool.uv]
default-groups = ["dev", "foo"]

要默认启用所有依赖组，请使用 "all" 而不是列出组名：

[tool.uv]
default-groups = "all"

tip

要在 uv run 或 uv sync 期间禁用此行为，请使用 --no-default-groups。要排除特定的默认组，请使用 --no-group <name>。