uv Cheatsheet — Dependencies

·Updated March 20th, 2026
pythonuvdependenciespackages

Add Dependencies

bash
# Add a package (latest compatible version)
uv add requests

# Add with version constraint
uv add 'requests>=2.31,<3'
uv add 'requests==2.31.0'

# Add multiple packages
uv add flask sqlalchemy celery

# Add from a git repository
uv add git+https://github.com/psf/requests

# Add from a git repo at a specific tag/branch
uv add git+https://github.com/psf/requests@v2.31.0
uv add git+https://github.com/psf/requests@main

# Add from a local path
uv add ./packages/my-lib

# Add as editable (for local development)
uv add --editable ./packages/my-lib

# Bulk-add from requirements.txt
uv add -r requirements.txt
uv add -r requirements.txt -c constraints.txt

Each uv add updates pyproject.toml, regenerates uv.lock, and syncs the environment.

Remove Dependencies

bash
uv remove requests

# Remove multiple
uv remove flask sqlalchemy

Upgrade Dependencies

bash
# Upgrade all dependencies to their latest compatible versions
uv lock --upgrade

# Upgrade a specific package
uv lock --upgrade-package requests

# Then sync the environment
uv sync

Optional Dependencies (extras)

Declare extras in pyproject.toml:

toml
[project.optional-dependencies]
plot = ["matplotlib>=3.6"]
excel = ["openpyxl>=3.1", "xlrd>=2.0"]

Install them:

bash
uv sync --extra plot
uv sync --all-extras

Add a dependency to an extra:

bash
uv add matplotlib --optional plot

Dependency Groups

Dependency groups (PEP 735) let you organize non-runtime dependencies:

toml
[dependency-groups]
dev = ["ruff>=0.8", "pytest>=8.3", "mypy>=1.11"]
test = ["pytest>=8.3", "coverage>=7.0"]
docs = ["sphinx>=7.0", "sphinx-rtd-theme"]
bash
# Add to a group
uv add --group dev ruff
uv add --group test pytest coverage

# Sync with specific groups
uv sync --group dev
uv sync --group dev --group test
uv sync --all-groups

# Sync without dev (dev is included by default)
uv sync --no-dev

Platform-Specific Dependencies (environment markers)

toml
[project]
dependencies = [
    "jax; sys_platform == 'linux'",
    "numpy>=1.26; python_version >= '3.12'",
    "uvloop; sys_platform != 'win32'",
]
bash
# Add with a marker from the CLI
uv add "uvloop; sys_platform != 'win32'"

Dependency Sources (tool.uv.sources)

Override where uv resolves a package from:

toml
[tool.uv.sources]
# Git source
requests = { git = "https://github.com/psf/requests", tag = "v2.31.0" }

# Local path
my-lib = { path = "../libs/my-lib", editable = true }

# Workspace member
shared-utils = { workspace = true }

# Specific index
torch = { index = "pytorch" }

Sources are for development only — they are stripped when publishing. To resolve without sources (as end users will):

bash
uv lock --no-sources

Constraint Dependencies

Force version bounds on transitive dependencies without declaring them as direct dependencies:

toml
[tool.uv]
constraint-dependencies = ["grpcio<1.65"]

Exclude Dependencies

Prevent a transitive dependency from being installed entirely:

toml
[tool.uv]
exclude-dependencies = ["werkzeug"]

Override Dependencies

Force a specific version regardless of what dependents request:

toml
[tool.uv]
override-dependencies = ["numpy==1.26.4"]