跳到内容

管理依赖

依赖字段

项目的依赖定义在多个字段中

注意

即使项目不打算发布，也可以使用 project.dependencies 和 project.optional-dependencies 字段。dependency-groups 是最近标准化的功能，可能尚未被所有工具支持。

uv 支持使用 uv add 和 uv remove 修改项目的依赖，但也可以通过直接编辑 pyproject.toml 来更新依赖元数据。

添加依赖

要添加依赖

$ uv add httpx

将在 project.dependencies 字段中添加一个条目

pyproject.toml
[project]
name = "example"
version = "0.1.0"
dependencies = ["httpx>=0.27.2"]

可以使用 --dev、--group 或 --optional 标志将依赖添加到替代字段。

依赖将包括约束，例如 >=0.27.2，对于软件包的最新兼容版本。可以使用 --bounds 调整绑定的种类，或者可以直接提供约束

$ uv add "httpx>=0.20"

当从包注册表以外的来源添加依赖时，uv 将在 sources 字段中添加一个条目。例如，当从 GitHub 添加 httpx 时

$ uv add "httpx @ git+https://github.com/encode/httpx"

pyproject.toml 将包含一个 Git 源条目

pyproject.toml
[project]
name = "example"
version = "0.1.0"
dependencies = [
    "httpx",
]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx" }

如果无法使用依赖，uv 将显示错误。

$ uv add "httpx>9999"
  × No solution found when resolving dependencies:
  ╰─▶ Because only httpx<=1.0.0b0 is available and your project depends on httpx>9999,
      we can conclude that your project's requirements are unsatisfiable.

导入依赖

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

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

有关升级包的更多详细信息，请参阅 lockfile 文档。

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

$ uv add "httpx @ ../httpx"

平台特定的依赖

要确保依赖项仅安装在特定平台或特定 Python 版本上，请使用 环境标记。

例如，在 Linux 上安装 jax，但在 Windows 或 macOS 上不安装

$ uv add "jax; sys_platform == 'linux'"

生成的 pyproject.toml 将在依赖定义中包含环境标记

pyproject.toml
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["jax; sys_platform == 'linux'"]

类似地，要在 Python 3.11 及更高版本上包含 numpy

$ uv add "numpy; python_version >= '3.11'"

有关可用标记和运算符的完整枚举，请参阅 Python 的 环境标记 文档。

提示

依赖源也可以 按平台更改。

项目依赖

project.dependencies 表表示上传到 PyPI 或构建 wheel 时使用的依赖项。单个依赖项使用 依赖说明符 语法指定，该表遵循 PEP 621 标准。

project.dependencies 定义了项目所需的包列表，以及安装它们时应使用的版本约束。每个条目都包括依赖项名称和版本。一个条目可能包括额外项或环境标记，用于特定于平台的包。例如

pyproject.toml
[project]
name = "albatross"
version = "0.1.0"
dependencies = [
  # Any version in this range
  "tqdm >=4.66.2,<5",
  # Exactly this version of torch
  "torch ==2.2.2",
  # Install transformers with the torch extra
  "transformers[torch] >=4.39.3,<5",
  # Only install this package on older python versions
  # See "Environment Markers" for more information
  "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
  "mollymawk ==0.1.0"
]

依赖源

tool.uv.sources 表使用替代依赖项源扩展了标准依赖项表，这些替代依赖项源在开发期间使用。

依赖源增加了对 project.dependencies 标准不支持的常见模式的支持，例如可编辑安装和相对路径。例如，要从相对于项目根目录的目录安装 foo

pyproject.toml
[project]
name = "example"
version = "0.1.0"
dependencies = ["foo"]

[tool.uv.sources]
foo = { path = "./packages/foo" }

uv 支持以下依赖源

  • 索引：从特定包索引解析的包。
  • Git：Git 存储库。
  • URL：远程 wheel 或源代码分发。
  • 路径：本地 wheel、源代码分发或项目目录。
  • 工作空间：当前工作空间的成员。

重要

源仅受 uv 尊重。如果使用其他工具，则仅使用标准项目表中的定义。如果另一个工具用于开发，则需要在另一个工具的格式中重新指定源表中提供的任何元数据。

索引

要从特定索引添加 Python 包，请使用 --index 选项

$ uv add torch --index pytorch=https://download.pytorch.org/whl/cpu

uv 将索引存储在 [[tool.uv.index]] 中，并添加一个 [tool.uv.sources] 条目

pyproject.toml
[project]
dependencies = ["torch"]

[tool.uv.sources]
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

提示

由于 PyTorch 索引的特殊性，上面的示例仅适用于 x86-64 Linux。有关设置 PyTorch 的更多信息，请参阅 PyTorch 指南。

使用 index 源 将 包 固定 到给定的索引 - 它不会从其他索引下载。

定义索引时，可以包含 explicit 标志以指示该索引应 仅 用于在 tool.uv.sources 中显式指定它的包。如果未设置 explicit，则如果未在其他地方找到，则其他包可能会从该索引解析。

pyproject.toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

Git

要添加 Git 依赖源，请使用 git+ 作为 Git 兼容 URL 的前缀。

例如

$ # Install over HTTP(S).
$ uv add git+https://github.com/encode/httpx

$ # Install over SSH.
$ uv add git+ssh://[email protected]/encode/httpx
pyproject.toml
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx" }

可以请求特定的 Git 引用，例如，标签

$ uv add git+https://github.com/encode/httpx --tag 0.27.0
pyproject.toml
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }

或者，分支

$ uv add git+https://github.com/encode/httpx --branch main
pyproject.toml
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", branch = "main" }

或者，修订（提交）

$ uv add git+https://github.com/encode/httpx --rev 326b9431c761e1ef1e00b9f760d1f654c8db48c6
pyproject.toml
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", rev = "326b9431c761e1ef1e00b9f760d1f654c8db48c6" }

如果包不在存储库根目录中，则可以指定 subdirectory

$ uv add git+https://github.com/langchain-ai/langchain#subdirectory=libs/langchain
pyproject.toml
[project]
dependencies = ["langchain"]

[tool.uv.sources]
langchain = { git = "https://github.com/langchain-ai/langchain", subdirectory = "libs/langchain" }

URL

要添加 URL 源，请提供一个 https:// URL，指向 wheel（以 .whl 结尾）或源代码分发（通常以 .tar.gz 或 .zip 结尾；有关所有支持的格式，请参阅 此处）。

例如

$ uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"

将导致一个 pyproject.toml 具有

pyproject.toml
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }

也可以使用 { url = <url> } 语法在 pyproject.toml 中手动添加或编辑 URL 依赖项。如果源代码分发不在存档根目录中，则可以指定 subdirectory。

路径

要添加路径源，请提供 wheel（以 .whl 结尾）、源代码分发（通常以 .tar.gz 或 .zip 结尾；有关所有支持的格式，请参阅 此处）或包含 pyproject.toml 的目录的路径。

例如

$ uv add /example/foo-0.1.0-py3-none-any.whl

将导致一个 pyproject.toml 具有

pyproject.toml
[project]
dependencies = ["foo"]

[tool.uv.sources]
foo = { path = "/example/foo-0.1.0-py3-none-any.whl" }

路径也可以是相对路径

$ uv add ./foo-0.1.0-py3-none-any.whl

或者，项目目录的路径

$ uv add ~/projects/bar/

重要

将目录用作路径依赖项时，默认情况下，uv 将尝试构建目标并将其作为包安装。有关详细信息，请参阅 虚拟依赖项 文档。

默认情况下，不使用 可编辑安装 用于路径依赖项。可以为项目目录请求可编辑安装

$ uv add --editable ../projects/bar/

这将导致一个 pyproject.toml 具有

pyproject.toml
[project]
dependencies = ["bar"]

[tool.uv.sources]
bar = { path = "../projects/bar", editable = true }

提示

对于同一存储库中的多个包，工作区 可能是更好的选择。

工作空间成员

要声明对工作区成员的依赖项，请添加成员名称和 { workspace = true }。必须显式声明所有工作区成员。工作区成员始终是 可编辑的 。有关工作区的更多详细信息，请参阅 工作区 文档。

pyproject.toml
[project]
dependencies = ["foo==0.1.0"]

[tool.uv.sources]
foo = { workspace = true }

[tool.uv.workspace]
members = [
  "packages/foo"
]

平台特定的源

您可以通过为源提供 依赖项说明符 兼容的环境标记，从而将源限制为给定的平台或 Python 版本。

例如，要从 GitHub 拉取 httpx，但仅在 macOS 上，请使用以下内容

pyproject.toml
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.2", marker = "sys_platform == 'darwin'" }

通过在源上指定标记，uv 仍将在所有平台上包含 httpx，但在 macOS 上从 GitHub 下载源，并在所有其他平台上回退到 PyPI。

多个源

您可以通过提供源列表（由 PEP 508 兼容的环境标记消歧）来为单个依赖项指定多个源。

例如，要在 macOS 与 Linux 上拉入不同的 httpx 标签

pyproject.toml
[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = [
  { git = "https://github.com/encode/httpx", tag = "0.27.2", marker = "sys_platform == 'darwin'" },
  { git = "https://github.com/encode/httpx", tag = "0.24.1", marker = "sys_platform == 'linux'" },
]

此策略扩展到基于环境标记使用不同的索引。例如，要根据平台从不同的 PyTorch 索引安装 torch

pyproject.toml
[project]
dependencies = ["torch"]

[tool.uv.sources]
torch = [
  { index = "torch-cpu", marker = "platform_system == 'Darwin'"},
  { index = "torch-gpu", marker = "platform_system == 'Linux'"},
]

[[tool.uv.index]]
name = "torch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu124"
explicit = true

禁用源

要指示 uv 忽略 tool.uv.sources 表（例如，要模拟使用包的已发布元数据进行解析），请使用 --no-sources 标志

$ uv lock --no-sources

使用 --no-sources 还会阻止 uv 发现任何可以满足给定依赖项的 工作区成员。

可选依赖

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

可选依赖项在 [project.optional-dependencies] 中指定，这是一个 TOML 表，它将额外项名称映射到其依赖项，遵循 依赖项说明符 语法。

可选依赖项可以像正常依赖项一样在 tool.uv.sources 中具有条目。

pyproject.toml
[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"
]

要添加可选依赖项，请使用 --optional <extra> 选项

$ uv add httpx --optional network

注意

如果您的可选依赖项相互冲突，则解析将失败，除非您显式地 将它们声明为冲突。

也可以将源声明为仅适用于特定的可选依赖项。例如，要根据可选的 cpu 或 gpu 额外项从不同的 PyTorch 索引拉取 torch

pyproject.toml
[project]
dependencies = []

[project.optional-dependencies]
cpu = [
  "torch",
]
gpu = [
  "torch",
]

[tool.uv.sources]
torch = [
  { index = "torch-cpu", extra = "cpu" },
  { index = "torch-gpu", extra = "gpu" },
]

[[tool.uv.index]]
name = "torch-cpu"
url = "https://download.pytorch.org/whl/cpu"

[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu124"

开发依赖

与可选依赖项不同，开发依赖项是本地专用的，并且 不会 在发布到 PyPI 或其他索引时包含在项目要求中。因此，开发依赖项不包含在 [project] 表中。

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

要添加开发依赖项，请使用 --dev 标志

$ uv add --dev pytest

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

pyproject.toml
[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] 定义

pyproject.toml
[dependency-groups]
dev = [
  "pytest"
]
lint = [
  "ruff"
]

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

提示

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

uv 要求所有依赖项组彼此兼容，并在创建 lockfile 时将所有组一起解析。

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

注意

如果您的依赖项组相互冲突，则解析将失败，除非您显式地 将它们声明为冲突。

嵌套组

依赖项组可以包含其他依赖项组，例如

pyproject.toml
[dependency-groups]
dev = [
  {include-group = "lint"},
  {include-group = "test"}
]
lint = [
  "ruff"
]
test = [
  "pytest"
]

包含的组的依赖项不能与组中声明的其他依赖项冲突。

默认组

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

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

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

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

提示

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

遗留的 dev-dependencies

在 [dependency-groups] 标准化之前，uv 使用 tool.uv.dev-dependencies 字段来指定开发依赖项，例如

pyproject.toml
[tool.uv]
dev-dependencies = [
  "pytest"
]

在此部分中声明的依赖项将与 dependency-groups.dev 中的内容组合在一起。最终，dev-dependencies 字段将被弃用和删除。

注意

如果存在 tool.uv.dev-dependencies 字段，uv add --dev 将使用现有部分，而不是添加新的 dependency-groups.dev 部分。

构建依赖

如果项目结构化为 Python 包，它可能会声明构建项目所需的依赖项，但运行该项目不需要这些依赖项。这些依赖项在 [build-system] 表的 build-system.requires 下指定，遵循 PEP 518。

例如，如果项目使用 setuptools 作为其构建后端，则应将 setuptools 声明为构建依赖项

pyproject.toml
[project]
name = "pandas"
version = "0.1.0"

[build-system]
requires = ["setuptools>=42"]
build-backend = "setuptools.build_meta"

默认情况下，uv 将在解析构建依赖项时遵守 tool.uv.sources。例如，要使用 setuptools 的本地版本进行构建，请将源添加到 tool.uv.sources

pyproject.toml
[project]
name = "pandas"
version = "0.1.0"

[build-system]
requires = ["setuptools>=42"]
build-backend = "setuptools.build_meta"

[tool.uv.sources]
setuptools = { path = "./packages/setuptools" }

发布包时，我们建议运行 uv build --no-sources 以确保当 tool.uv.sources 被禁用时，包能够正确构建，就像在使用其他构建工具（如 pypa/build）时一样。

可编辑依赖

使用 Python 包的目录的常规安装首先构建一个 wheel，然后将该 wheel 安装到您的虚拟环境中，复制所有源文件。当编辑包源文件时，虚拟环境将包含过时的版本。

可编辑安装通过在虚拟环境中添加指向项目的链接（.pth 文件）来解决此问题，该文件指示解释器直接包含源文件。

可编辑项有一些限制（主要：构建后端需要支持它们，并且本机模块在导入之前不会重新编译），但它们对于开发很有用，因为虚拟环境将始终使用对包的最新更改。

默认情况下，uv 将可编辑安装用于工作区包。

要添加可编辑依赖项，请使用 --editable 标志

$ uv add --editable ./path/foo

或者，要选择不使用工作区中的可编辑依赖项

$ uv add --no-editable ./path/foo

虚拟依赖

uv 允许依赖项是“虚拟的”，其中依赖项本身不会作为 包 安装，但其依赖项会被安装。

默认情况下，依赖项永远不是虚拟的。

如果 path 源 显式设置 tool.uv.package = false，则具有该源的依赖项可以是虚拟的。与使用 uv 在 从属项目中工作不同，即使未声明 构建系统，也会构建该包。

要将依赖项视为虚拟的，请在源上设置 package = false

pyproject.toml
[project]
dependencies = ["bar"]

[tool.uv.sources]
bar = { path = "../projects/bar", package = false }

如果依赖项设置 tool.uv.package = false，则可以通过在源上声明 package = true 来覆盖它

pyproject.toml
[project]
dependencies = ["bar"]

[tool.uv.sources]
bar = { path = "../projects/bar", package = true }

类似地，如果 workspace 源 显式设置 tool.uv.package = false，则具有该源的依赖项可以是虚拟的。即使未声明 构建系统，也会构建工作区成员。

默认情况下，不 是依赖项的工作区成员可以是虚拟的，例如，如果父 pyproject.toml 是

pyproject.toml
[project]
name = "parent"
version = "1.0.0"
dependencies = []

[tool.uv.workspace]
members = ["child"]

并且子 pyproject.toml 排除了一个构建系统

pyproject.toml
[project]
name = "child"
version = "1.0.0"
dependencies = ["anyio"]

那么 child 工作区成员将不会被安装，但可传递依赖项 anyio 将会被安装。

相反，如果父级声明了对 child 的依赖项

pyproject.toml
[project]
name = "parent"
version = "1.0.0"
dependencies = ["child"]

[tool.uv.sources]
child = { workspace = true }

[tool.uv.workspace]
members = ["child"]

那么 child 将被构建和安装。

依赖说明符

uv 使用标准 依赖项说明符，最初在 PEP 508 中定义。依赖项说明符按顺序由以下部分组成

  • 依赖项名称
  • 您想要的额外项（可选）
  • 版本说明符
  • 环境标记（可选）

版本说明符用逗号分隔并添加到一起，例如，foo >=1.2.3,<2,!=1.4.0 被解释为“foo 的版本至少为 1.2.3，但小于 2，且不为 1.4.0”。

如果需要，说明符将填充尾随零，因此 foo ==2 也匹配 foo 2.0.0。

星号可以用于最后一位数字，例如，foo ==2.1.* 将接受 2.1 系列中的任何版本。类似地，~= 匹配最后一位数字等于或更高的地方，例如，foo ~=1.2 等于 foo >=1.2,<2，并且 foo ~=1.2.3 等于 foo >=1.2.3,<1.3。

额外项在名称和版本之间的方括号中用逗号分隔，例如，pandas[excel,plot] ==2.2。额外名称之间的空格将被忽略。

某些依赖项仅在特定环境中需要，例如，特定的 Python 版本或操作系统。例如，要为 importlib.metadata 模块安装 importlib-metadata 向后移植，请使用 importlib-metadata >=7.1.0,<8; python_version < '3.10'。要在 Windows 上安装 colorama（但在其他平台上省略它），请使用 colorama >=0.4.6,<5; platform_system == "Windows"。

标记与 and、or 和括号组合在一起，例如，aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'。请注意，标记内的版本必须用引号引起来，而标记 外部 的版本 不得 用引号引起来。