This document covers uv's project command system, which provides high-level commands for managing Python projects and PEP 723 scripts. These commands handle dependency management, environment synchronization, code execution, and lockfile operations.
For details about lockfile format and validation, see Lockfile Management. For dependency group and extras handling, see Dependency Operations.
Project commands operate on either workspace projects (with pyproject.toml) or PEP 723 scripts (with inline metadata). Each command follows a consistent pattern of discovery, validation, and execution.
Sources: crates/uv/src/commands/project/mod.rs71-87 crates/uv/src/commands/project/run.rs88-123 crates/uv/src/commands/project/lock.rs87-106 crates/uv/src/commands/project/sync.rs65-95 crates/uv/src/commands/project/upgrade.rs1-20
All project commands rely on shared state management and environment handling:
| Component | Purpose | Key Types |
|---|---|---|
UniversalState | Universal resolution state (fork-aware) | crates/uv/src/commands/project/mod.rs167 |
LockMode | Controls lockfile behavior (Write, Locked, Frozen, DryRun) | crates/uv/src/commands/project/lock.rs145-202 |
LockTarget | Identifies lock subject (Workspace or Script) | crates/uv/src/commands/project/lock_target.rs8-11 |
InstallTarget | Identifies sync target | crates/uv/src/commands/project/install_target.rs11-16 |
ProjectInterpreter | Logic for project-based Python discovery | crates/uv/src/commands/project/mod.rs472-486 |
ScriptInterpreter | Logic for script-based Python discovery | crates/uv/src/commands/project/mod.rs567-578 |
LockedTool | Mechanism for running tools from dependency groups | crates/uv/src/commands/project/toolchain.rs10-25 |
Sources: crates/uv/src/commands/project/mod.rs1-81 crates/uv/src/commands/project/lock.rs145-202 crates/uv/src/commands/project/run.rs69-77 crates/uv/src/commands/project/toolchain.rs1-40
The run command executes commands within project or script environments, handling dependency resolution and environment synchronization automatically. It also supports PEP 723 inline metadata for single-file scripts. It uses LockedTool from toolchain.rs to execute tools defined in project dependency groups.
Sources: crates/uv/src/commands/project/run.rs124-134 crates/uv/src/commands/project/run.rs180-200 crates/uv/src/commands/project/run.rs210-499 crates/uv/src/commands/project/run.rs88-123 crates/uv/src/commands/project/toolchain.rs10-25
The lock command resolves project requirements into a uv.lock file. It supports universal resolution, meaning it can generate a single lockfile that satisfies multiple platforms and Python versions.
Sources: crates/uv/src/commands/project/lock.rs108-128 crates/uv/src/commands/project/lock.rs131-143 crates/uv/src/commands/project/lock.rs145-202
The sync command ensures the virtual environment matches the lockfile. It handles the full pipeline of planning, downloading, and installing distributions.
Sources: crates/uv/src/commands/project/sync.rs104-147 crates/uv/src/commands/project/sync.rs162-195 crates/uv/src/commands/project/sync.rs65-95
The add command updates the pyproject.toml or script metadata and immediately performs a resolution and sync (unless --no-sync is specified). It supports the add-bounds preview feature (stabilized in 0.10.0) for controlling version constraint generation via AddBoundsKind.
Sources: crates/uv/src/commands/project/add.rs170-213 crates/uv/src/commands/project/add.rs46-50 crates/uv/src/commands/project/add.rs71-114 crates/uv/src/commands/project/add.rs91
The init command sets up the basic structure for a Python project or script. The packaged-init preview feature changes the default behavior to create packaged applications.
| Action | Function | File |
|---|---|---|
| Script Initialization | init_script() | crates/uv/src/commands/project/init.rs201-218 |
| Project Initialization | init_project() | crates/uv/src/commands/project/init.rs312-334 |
| VCS Setup | initialize_vcs() | crates/uv/src/commands/project/init.rs601-605 |
Sources: crates/uv/src/commands/project/init.rs44-67 crates/uv/src/commands/project/init.rs101-143
pyproject.toml or script metadata using PyProjectTomlMut.
requirements.txt or cyclonedx JSON. Includes the sbom-export preview feature.
pyproject.toml. Supports bumping major, minor, patch, and prerelease versions.
uv_audit::osv.
uv-bin-install. Upgraded to Ruff 0.15.0 (2026 style) in 0.10.0. Supports version constraints and exclude-newer in preview. Custom binary paths can be provided via the RUFF environment variable.
ty. This command is powered by uv-bin-install. Custom binary paths can be provided via the TY environment variable. The --script flag and workspace-metadata preview feature allow passing structured JSON to the checker.
pyproject.toml to its latest version.
The uv format and uv check commands use the uv-bin-install crate to manage external tools that are not standard Python packages.
Sources: crates/uv/src/commands/project/check/ty.rs39-51 crates/uv/src/commands/project/check/ty.rs146-175
The project system includes comprehensive validation to ensure consistency between configuration, lockfiles, and environments:
uv.lock is out of sync with pyproject.toml.
requires-python constraints.
uv.lock schema version is supported by the current uv binary. Supports schema version detection and upgrade paths.
Refresh this wiki