uv-advanced-dependencies

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UV Advanced Dependencies

UV 高级依赖

Quick reference for advanced dependency scenarios in UV projects.
UV 项目中高级依赖场景的快速参考。

When to Use This Skill

何时使用此 Skill

Use this skill when...Use a focused sibling instead when...
Pinning a dependency to a git URL, branch, or tag, or installing in editable modeAdding a normal PyPI dependency — use uv-project-management
Configuring
[tool.uv.sources]
, dependency groups, extras, or custom indexes
Sharing source declarations across workspace members — use uv-workspaces
Setting up private package indexes or build-time constraintsRunning an ephemeral script with
--with
deps — use uv-run
使用此 Skill 的场景何时改用更聚焦的同级 Skill
将依赖固定到 Git URL、分支或标签,或以可编辑模式安装添加普通 PyPI 依赖——使用 uv-project-management
配置
[tool.uv.sources]
、依赖组、extras 或自定义索引
在工作区成员之间共享源声明——使用 uv-workspaces
设置私有包索引或构建时约束使用
--with
依赖运行临时脚本——使用 uv-run

When This Skill Applies

适用场景

  • Git repository dependencies
  • Local path dependencies
  • Editable installations
  • Dependency constraints
  • Custom package indexes
  • Dependency groups and extras
  • Build dependencies
  • Git 仓库依赖
  • 本地路径依赖
  • 可编辑安装
  • 依赖约束
  • 自定义包索引
  • 依赖组和 extras
  • 构建依赖

Quick Reference

快速参考

Git Dependencies

Git 依赖

bash
undefined
bash
undefined

Add from Git repository

Add from Git repository

uv add git+https://github.com/psf/requests uv add git+https://github.com/pallets/flask@main uv add git+ssh://git@github.com/user/repo.git@v1.0.0
uv add git+https://github.com/psf/requests uv add git+https://github.com/pallets/flask@main uv add git+ssh://git@github.com/user/repo.git@v1.0.0

Specific branch, tag, or commit

Specific branch, tag, or commit

Path Dependencies

路径依赖

bash
undefined
bash
undefined

Add from local path

Add from local path

uv add --editable ./local-package uv add ../another-project uv add /absolute/path/to/package
uv add --editable ./local-package uv add ../another-project uv add /absolute/path/to/package

Non-editable path

Non-editable path

uv add --no-editable ./local-package
undefined
uv add --no-editable ./local-package
undefined

Dependency Groups

依赖组

bash
undefined
bash
undefined

Add to named group

Add to named group

uv add --group docs sphinx mkdocs uv add --group test pytest pytest-cov
uv add --group docs sphinx mkdocs uv add --group test pytest pytest-cov

Install specific groups

Install specific groups

uv sync --group docs uv sync --group test --group docs
uv sync --group docs uv sync --group test --group docs

Install all groups

Install all groups

uv sync --all-groups
undefined
uv sync --all-groups
undefined

Extras (Optional Dependencies)

extras(可选依赖)

bash
undefined
bash
undefined

Install package with extras

Install package with extras

uv add 'fastapi[all]' uv add 'sqlalchemy[postgresql,mypy]'
uv add 'fastapi[all]' uv add 'sqlalchemy[postgresql,mypy]'

Define extras in pyproject.toml

Define extras in pyproject.toml

[project.optional-dependencies] dev = ["pytest", "ruff"] docs = ["mkdocs", "mkdocs-material"]
undefined
[project.optional-dependencies] dev = ["pytest", "ruff"] docs = ["mkdocs", "mkdocs-material"]
undefined

Constraint Files

约束文件

bash
undefined
bash
undefined

Apply version constraints

Apply version constraints

uv pip compile requirements.in --constraint constraints.txt
uv pip compile requirements.in --constraint constraints.txt

constraints.txt example:

constraints.txt example:

numpy<2.0

numpy<2.0

pandas==2.0.3

pandas==2.0.3

undefined
undefined

Custom Indexes

自定义索引

toml
[tool.uv]
index-url = "https://pypi.org/simple"
extra-index-url = [
    "https://custom.pypi.org/simple",
]
toml
[tool.uv]
index-url = "https://pypi.org/simple"
extra-index-url = [
    "https://custom.pypi.org/simple",
]

Git Dependencies in pyproject.toml

pyproject.toml 中的 Git 依赖

toml
[project]
dependencies = [
    "my-package",
]

[tool.uv.sources]
my-package = { git = "https://github.com/user/my-package" }
toml
[project]
dependencies = [
    "my-package",
]

[tool.uv.sources]
my-package = { git = "https://github.com/user/my-package" }

With branch

With branch

my-package = { git = "https://github.com/user/my-package", branch = "main" }
my-package = { git = "https://github.com/user/my-package", branch = "main" }

With tag

With tag

my-package = { git = "https://github.com/user/my-package", tag = "v1.0.0" }
my-package = { git = "https://github.com/user/my-package", tag = "v1.0.0" }

With commit

With commit

my-package = { git = "https://github.com/user/my-package", rev = "abc123" }
undefined
my-package = { git = "https://github.com/user/my-package", rev = "abc123" }
undefined

Path Dependencies in pyproject.toml

pyproject.toml 中的路径依赖

toml
[project]
dependencies = [
    "my-local-package",
]

[tool.uv.sources]
my-local-package = { path = "../my-local-package" }
toml
[project]
dependencies = [
    "my-local-package",
]

[tool.uv.sources]
my-local-package = { path = "../my-local-package" }

Editable (default for paths)

Editable (default for paths)

my-local-package = { path = "../my-local-package", editable = true }
my-local-package = { path = "../my-local-package", editable = true }

Non-editable

Non-editable

my-local-package = { path = "../my-local-package", editable = false }
undefined
my-local-package = { path = "../my-local-package", editable = false }
undefined

Dependency Groups

依赖组

toml
[dependency-groups]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "ruff>=0.1.0",
]
docs = [
    "mkdocs-material>=9.0",
    "mkdocstrings[python]>=0.24",
]
test = [
    "pytest-asyncio>=0.21",
    "pytest-mock>=3.12",
]
toml
[dependency-groups]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "ruff>=0.1.0",
]
docs = [
    "mkdocs-material>=9.0",
    "mkdocstrings[python]>=0.24",
]
test = [
    "pytest-asyncio>=0.21",
    "pytest-mock>=3.12",
]

URL Dependencies

URL 依赖

bash
undefined
bash
undefined

Add from direct URL

Add from direct URL

In pyproject.toml

In pyproject.toml

[tool.uv.sources] my-package = { url = "https://example.com/my-package-1.0.tar.gz" }
undefined
[tool.uv.sources] my-package = { url = "https://example.com/my-package-1.0.tar.gz" }
undefined

Private Package Indexes

私有包索引

toml
[tool.uv]
toml
[tool.uv]

Primary index

Primary index

Additional indexes

Additional indexes

extra-index-url = [ "https://${PRIVATE_TOKEN}@private.pypi.org/simple", ]
extra-index-url = [ "https://${PRIVATE_TOKEN}@private.pypi.org/simple", ]

Find links

Find links


```bash

```bash

Set token via environment

Set token via environment

export PRIVATE_TOKEN="secret" uv sync
undefined
export PRIVATE_TOKEN="secret" uv sync
undefined

Build Dependencies

构建依赖

toml
[build-system]
requires = [
    "setuptools>=68",
    "wheel",
    "Cython>=3.0",
]
build-backend = "setuptools.build_meta"
toml
[build-system]
requires = [
    "setuptools>=68",
    "wheel",
    "Cython>=3.0",
]
build-backend = "setuptools.build_meta"

Common Patterns

常见模式

Development from Local Checkout

从本地检出进行开发

bash
undefined
bash
undefined

Clone dependency

Clone dependency

Add as editable

Add as editable

cd my-project uv add --editable ../lib
undefined
cd my-project uv add --editable ../lib
undefined

Monorepo Path Dependencies

Monorepo 路径依赖

toml
[tool.uv.sources]
my-core = { path = "packages/core" }
my-utils = { path = "packages/utils" }
toml
[tool.uv.sources]
my-core = { path = "packages/core" }
my-utils = { path = "packages/utils" }

Mixed Sources

混合来源

toml
[project]
dependencies = [
    "fastapi",          # PyPI
    "my-lib",           # Git
    "my-local",         # Path
]

[tool.uv.sources]
my-lib = { git = "https://github.com/user/my-lib" }
my-local = { path = "../my-local" }
toml
[project]
dependencies = [
    "fastapi",          # PyPI
    "my-lib",           # Git
    "my-local",         # Path
]

[tool.uv.sources]
my-lib = { git = "https://github.com/user/my-lib" }
my-local = { path = "../my-local" }

Resolution Strategies

解析策略

toml
[tool.uv]
toml
[tool.uv]

Highest compatible (default)

Highest compatible (default)

resolution = "highest"
resolution = "highest"

Lowest compatible

Lowest compatible

resolution = "lowest"
resolution = "lowest"

Lowest direct, highest transitive

Lowest direct, highest transitive

resolution = "lowest-direct"
undefined
resolution = "lowest-direct"
undefined

See Also

另请参阅

  • uv-project-management
    - Basic dependency management
  • uv-workspaces
    - Workspace member dependencies
  • python-packaging
    - Build system configuration
  • uv-project-management
    - 基础依赖管理
  • uv-workspaces
    - 工作区成员依赖
  • python-packaging
    - 构建系统配置

References

参考资料