Project workflow

The "project" workflow is uv's pyproject.toml-centric path: uv init, uv add, uv remove, uv sync, uv run, uv lock, uv version. These commands all share a common shape:

1. Discover the workspace.
2. Load pyproject.toml and any uv.toml.
3. Optionally re-resolve into uv.lock (Dependency resolution).
4. Optionally re-install (crates/uv-installer).
5. Optionally mutate pyproject.toml (crates/uv-workspace pyproject_mut.rs).
6. Optionally spawn the user's process (uv run).

uv init

flowchart LR
    user[uv init my-pkg] --> py[Pick Python via uv-python]
    py --> tpl[Materialize template files]
    tpl --> readme[README, src/my_pkg/__init__.py]
    tpl --> py_proj[Write pyproject.toml]
    tpl --> git[git init + initial .gitignore]

Key files:

• crates/uv/src/commands/init.rs — the orchestrator.
• crates/uv-workspace/src/pyproject.rs — the PyProjectToml defaults.
• The template strings live alongside init.rs.

uv add / uv remove

uv add ruff is more involved than it looks:

1. Parse the requirement string with uv-pep508.
2. Resolve to find the actual version range it'll lock (so the inserted spec has correct bounds).
3. Insert via PyProjectTomlMut — preserving formatting, comments, and existing ordering.
4. Re-lock and re-sync if the working venv exists.

The insertion logic is the bulk of crates/uv-workspace/src/pyproject_mut.rs (~78 KB). Tests for it are in crates/uv/tests/it/edit.rs.

uv sync

uv sync is the workhorse: ensure the venv matches the lockfile.

1. Read uv.lock.
2. Filter to the packages enabled by current extras / groups.
3. Diff against the venv via uv-installer's Plan.
4. Apply the plan: download, unpack, install.

Edge cases:

• --locked — refuse to write a new lock; fail if the current one is stale.
• --frozen — don't lock; install from the existing lockfile as-is.
• --inexact — don't remove pre-existing extra packages.
• --all-extras / --extra X / --no-default-groups / --group dev.

uv run

uv run pytest:

1. Sync the project (unless --no-sync).
2. Resolve any extra --with dependencies into an overlay environment.
3. Find the executable: in the venv's bin/, then PATH within the venv.
4. Spawn it with the venv's environment.

crates/uv/src/commands/project/run.rs is the orchestrator.

See also

• features/dependency-resolution.
• crates/uv-workspace, crates/uv-installer, crates/uv-resolver.