Uv Advanced Dependencies

UV Advanced Dependencies

Quick reference for advanced dependency scenarios in UV projects.

When to Use This Skill

When This Skill Applies

• Git repository dependencies
• Local path dependencies
• Editable installations
• Dependency constraints
• Custom package indexes
• Dependency groups and extras
• Build dependencies

Quick Reference

Git Dependencies

# 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

# Specific branch, tag, or commit
uv add git+https://github.com/user/repo@feature-branch
uv add git+https://github.com/user/repo@v2.0.0
uv add git+https://github.com/user/repo@abc123

Path Dependencies

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

# Non-editable path
uv add --no-editable ./local-package

Dependency Groups

# Add to named group
uv add --group docs sphinx mkdocs
uv add --group test pytest pytest-cov

# Install specific groups
uv sync --group docs
uv sync --group test --group docs

# Install all groups
uv sync --all-groups

Extras (Optional Dependencies)

# Install package with extras
uv add 'fastapi[all]'
uv add 'sqlalchemy[postgresql,mypy]'

# Define extras in pyproject.toml
[project.optional-dependencies]
dev = ["pytest", "ruff"]
docs = ["mkdocs", "mkdocs-material"]

Constraint Files

# Apply version constraints
uv pip compile requirements.in --constraint constraints.txt

# constraints.txt example:
# numpy<2.0
# pandas==2.0.3

Custom Indexes

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

Git Dependencies in pyproject.toml

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

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

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

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

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

Path Dependencies in pyproject.toml

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

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

# Editable (default for paths)
my-local-package = { path = "../my-local-package", editable = true }

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

Dependency Groups

[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

# Add from direct URL
uv add https://files.pythonhosted.org/packages/.../requests-2.31.0.tar.gz

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

Private Package Indexes

[tool.uv]
# Primary index
index-url = "https://pypi.org/simple"

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

# Find links
find-links = [
    "https://download.pytorch.org/whl/cu118",
]

# Set token via environment
export PRIVATE_TOKEN="secret"
uv sync

Build Dependencies

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

Common Patterns

Development from Local Checkout

# Clone dependency
git clone https://github.com/user/lib.git ../lib

# Add as editable
cd my-project
uv add --editable ../lib

Monorepo Path Dependencies

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

Mixed Sources

[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

[tool.uv]
# Highest compatible (default)
resolution = "highest"

# Lowest compatible
resolution = "lowest"

# Lowest direct, highest transitive
resolution = "lowest-direct"

See Also

• uv-project-management - Basic dependency management
• uv-workspaces - Workspace member dependencies
• python-packaging - Build system configuration

References

• Official docs: https://docs.astral.sh/uv/concepts/dependencies/
• Detailed guide: See REFERENCE.md in this skill directory

UV Advanced Dependencies - Comprehensive Reference

Complete guide to advanced dependency scenarios in UV projects.

Table of Contents

1. Git Dependencies 2. Path Dependencies 3. URL Dependencies 4. Dependency Groups 5. Optional Dependencies (Extras) 6. Constraint Files 7. Custom Package Indexes 8. Build Dependencies 9. Resolution Strategies 10. Best Practices

---

Git Dependencies

Adding Git Dependencies

# HTTPS
uv add git+https://github.com/psf/requests

# SSH
uv add git+ssh://git@github.com/user/repo.git

# With subdirectory
uv add 'git+https://github.com/user/mono.git#subdirectory=packages/lib'

Specifying Refs

# Branch
uv add git+https://github.com/user/repo@main
uv add git+https://github.com/user/repo@develop

# Tag
uv add git+https://github.com/user/repo@v1.0.0

# Commit SHA
uv add git+https://github.com/user/repo@abc1234567890

pyproject.toml Configuration

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

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

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

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

# Commit
my-package = { git = "https://github.com/user/my-package", rev = "abc1234" }

# Subdirectory
my-package = { git = "https://github.com/user/mono", subdirectory = "packages/lib" }

Authentication

# SSH keys (recommended)
uv add git+ssh://git@github.com/user/private-repo.git

# HTTPS with token
export GIT_TOKEN="ghp_..."
uv add git+https://${GIT_TOKEN}@github.com/user/private-repo.git

# Git credentials helper
git config --global credential.helper store

---

Path Dependencies

Adding Path Dependencies

# Relative path (editable by default)
uv add ../my-local-package
uv add ./local-lib

# Absolute path
uv add /home/user/projects/my-package

# Explicit editable
uv add --editable ./local-package

# Non-editable
uv add --no-editable ./local-package

pyproject.toml Configuration

[project]
dependencies = ["my-local"]

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

# Editable (default for local paths)
my-local = { path = "../my-local", editable = true }

# Non-editable
my-local = { path = "../my-local", editable = false }

Use Cases

Development workflow:

# Clone dependency
git clone https://github.com/user/lib.git ../lib

# Add as editable
uv add --editable ../lib

# Changes to ../lib immediately available

Monorepo:

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

---

URL Dependencies

Direct URLs

# HTTP/HTTPS URL
uv add https://example.com/package-1.0.tar.gz

# Wheel file
uv add https://example.com/package-1.0-py3-none-any.whl

pyproject.toml Configuration

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

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

Find Links

[tool.uv]
find-links = [
    "https://download.pytorch.org/whl/cu118",
    "file:///local/packages/",
]

---

Dependency Groups

Modern Dependency Groups

[dependency-groups]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "ruff>=0.1.0",
    "mypy>=1.7",
]
docs = [
    "mkdocs-material>=9.0",
    "mkdocstrings[python]>=0.24",
]
test = [
    "pytest-asyncio>=0.21",
    "httpx>=0.25",
]

Installing Groups

# Install specific group
uv sync --group docs

# Multiple groups
uv sync --group dev --group test

# All groups
uv sync --all-groups

# Exclude dev (production)
uv sync --no-dev

Legacy Optional Dependencies

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

# Install extras
uv pip install -e .[dev]
uv sync --extra dev

---

Optional Dependencies (Extras)

Defining Extras

[project.optional-dependencies]
postgresql = ["psycopg2>=2.9"]
mysql = ["PyMySQL>=1.1"]
all = [
    "psycopg2>=2.9",
    "PyMySQL>=1.1",
]

Installing with Extras

# Single extra
uv add 'sqlalchemy[postgresql]'

# Multiple extras
uv add 'fastapi[all]'
uv add 'sqlalchemy[postgresql,mypy]'

# In requirements
uv pip install 'package[extra1,extra2]'

---

Constraint Files

Creating Constraints

# constraints.txt
numpy<2.0
pandas==2.0.3
scipy>=1.11,<2.0

Applying Constraints

# During compilation
uv pip compile requirements.in --constraint constraints.txt

# During installation
uv pip install -r requirements.txt --constraint constraints.txt

Build Constraints

# build-constraints.txt
setuptools==75.0.0
wheel==0.42.0

uv pip compile pyproject.toml --build-constraint build-constraints.txt

---

Custom Package Indexes

Configuration

[tool.uv]
# Primary index
index-url = "https://pypi.org/simple"

# Additional indexes (searched in order)
extra-index-url = [
    "https://custom.pypi.org/simple",
    "https://corporate.packages.com/simple",
]

Private Indexes with Authentication

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

# Set token
export PRIVATE_TOKEN="secret-token"
uv sync

Per-Package Index

[tool.uv.sources]
my-package = { index = "custom-index" }

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

---

Build Dependencies

Build System Configuration

[build-system]
requires = [
    "setuptools>=68",
    "setuptools-scm>=8",
    "wheel",
]
build-backend = "setuptools.build_meta"

Build Dependencies with Constraints

[build-system]
requires = [
    "hatchling>=1.18",
    "numpy>=2.0; python_version>='3.9'",
]

---

Resolution Strategies

Configuration

[tool.uv]
# Highest compatible versions (default)
resolution = "highest"

# Lowest compatible versions
resolution = "lowest"

# Lowest direct, highest transitive
resolution = "lowest-direct"

Use Cases

Highest (default):

• Normal development
• Get latest features and fixes

Lowest:

• Test minimum supported versions
• Ensure compatibility

Lowest-direct:

• Conservative updates
• Stable dependencies

---

Best Practices

1. Prefer PyPI When Possible

# ✅ Good
uv add requests

# ⚠️ Use only when needed
uv add git+https://github.com/psf/requests

2. Pin Git Dependencies

# ❌ Bad - unstable
my-package = { git = "https://github.com/user/pkg", branch = "main" }

# ✅ Good - stable
my-package = { git = "https://github.com/user/pkg", tag = "v1.0.0" }
my-package = { git = "https://github.com/user/pkg", rev = "abc1234" }

3. Document Custom Sources

# pyproject.toml
[tool.uv.sources]
# Corporate package repository
my-internal = { index = "corporate" }

# Development dependency from local checkout
my-dev-lib = { path = "../my-dev-lib", editable = true }

4. Use Dependency Groups

[dependency-groups]
dev = ["pytest", "ruff"]
docs = ["mkdocs"]

5. Secure Private Indexes

# Use environment variables
export PRIVATE_TOKEN="..."

# Never commit tokens
echo "PRIVATE_TOKEN=secret" >> .env
echo ".env" >> .gitignore

---

Related Skills

• uv-project-management - Basic dependency management
• uv-workspaces - Workspace dependencies
• python-packaging - Build configuration

---

References

• Official Docs: https://docs.astral.sh/uv/concepts/dependencies/
• Git URLs: https://pip.pypa.io/en/stable/topics/vcs-support/
• PEP 508: https://peps.python.org/pep-0508/ (dependency specification)