This page covers the mechanisms for adding and removing dependencies in uv projects and scripts. Dependency operations modify pyproject.toml (or PEP 723 script metadata) while maintaining lockfile consistency and synchronizing the environment.
Dependency operations in uv support two execution contexts:
| Context | Configuration File | Lock Target | Environment |
|---|---|---|---|
| Project | pyproject.toml | uv.lock | .venv/ or managed environment |
| Script | Inline PEP 723 metadata | Optional {script}.lock | Cached script environment |
Both contexts share the same underlying machinery for dependency mutation, resolution, and installation, implemented through the PyProjectTomlMut API [crates/uv-workspace/src/pyproject_mut.rs:26-29].
The following diagram bridges the user's intent (natural language commands) to the specific code entities responsible for processing them.
Sources: [crates/uv-workspace/src/pyproject_mut.rs:26-29], [crates/uv-requirements/src/specification.rs:59-92], [crates/uv-requirements/src/sources.rs:11-33]
The uv add and uv remove commands provide the primary interface for modifying project requirements. These commands follow a pattern of discovering the project, mutating the TOML, and then performing a lock and sync operation.
The PyProjectTomlMut structure provides the low-level API for modifying TOML documents while preserving formatting and comments [crates/uv-workspace/src/pyproject_mut.rs:22-25]. It uses toml_edit::DocumentMut for manipulation [crates/uv-workspace/src/pyproject_mut.rs:27].
The mutation process handles several dependency types defined in the DependencyType enum [crates/uv-workspace/src/pyproject_mut.rs:20-20]:
project.dependencies.dependency-groups [crates/uv-pypi-types/src/lib.rs:3-3].project.optional-dependencies.Sources: [crates/uv-workspace/src/pyproject_mut.rs:22-29], [crates/uv-workspace/src/pyproject_mut.rs:20-20], [crates/uv-pypi-types/src/lib.rs:3-3]
When adding a package without a version specifier, uv resolves the latest compatible version and generates a specifier based on the AddBoundsKind [crates/uv-workspace/src/pyproject_mut.rs:104-120].
| Bound Kind | Logic | Implementation |
|---|---|---|
| Lower | >=1.2.3 | Only a lower bound (default) [crates/uv-workspace/src/pyproject_mut.rs:106-107] |
| Major | >=1.2.3, <2.0.0 | Semver-style caret; bumps most significant non-zero digit [crates/uv-workspace/src/pyproject_mut.rs:108-111] |
| Minor | >=1.2.3, <1.3.0 | Semver-style tilde; bumps second significant digit [crates/uv-workspace/src/pyproject_mut.rs:112-115] |
| Exact | ==1.2.3 | Exact version pin [crates/uv-workspace/src/pyproject_mut.rs:116-120] |
The logic for Major and Minor bounds handles leading zeros to provide Semver-style semantics for 0.x versions (e.g., 0.1.2 -> 0.2.0 for Major) [crates/uv-workspace/src/pyproject_mut.rs:143-160].
Sources: [crates/uv-workspace/src/pyproject_mut.rs:104-120], [crates/uv-workspace/src/pyproject_mut.rs:133-176]
uv supports several dependency source types beyond standard registry packages, often configured in the tool.uv.sources table.
These sources are represented by the Source and Sources structs during TOML mutation [crates/uv-workspace/src/pyproject_mut.rs:20-20]. The index_locations_equal helper ensures that index URLs are compared canonically when updating source specifications [crates/uv-workspace/src/pyproject_mut.rs:31-44].
Sources: [crates/uv-workspace/src/pyproject_mut.rs:13-20], [crates/uv-workspace/src/pyproject_mut.rs:31-44]
uv implements PEP 735 style dependency groups. These are managed via the DependencyGroups configuration [crates/uv-requirements/src/specification.rs:40-42].
pyproject.toml under dependency-groups or within PEP 723 script metadata [crates/uv-requirements/src/specification.rs:121-135].RequirementsSpecification struct collects groups from source trees to inform the resolver [crates/uv-requirements/src/specification.rs:76-77].Sources: [crates/uv-requirements/src/specification.rs:40-42], [crates/uv-requirements/src/specification.rs:76-77], [crates/uv-requirements/src/specification.rs:121-135]
For PEP 723 scripts, dependency operations target the inline metadata block rather than a standalone pyproject.toml.
Pep723Script::read function extracts the /// script tag from Python files [crates/uv-scripts/src/lib.rs:173-196].RequirementsSpecification::from_pep723_metadata converts the parsed script metadata into unresolved requirements, constraints, and overrides [crates/uv-requirements/src/specification.rs:105-163].tool.uv.index, which are extracted via Pep723ItemRef::indexes [crates/uv-scripts/src/lib.rs:99-111].Sources: [crates/uv-scripts/src/lib.rs:173-196], [crates/uv-requirements/src/specification.rs:105-163], [crates/uv-scripts/src/lib.rs:99-111]