uv

crates/uv/ is the binary crate — it's where the uv and uvx executables come from. Almost everything else in the workspace is a library; this crate is the orchestrator that wires the libraries together, parses arguments, resolves settings, dispatches commands, and prints results.

Purpose

The crate has three responsibilities:

1. Argument dispatch. crates/uv/src/lib.rs::run (the top-level async function) reads the parsed Clap structure from uv-cli, figures out which command is being asked for, and routes to the right handler.
2. Settings resolution. crates/uv/src/settings.rs (~157 KB) defines per-command settings structs and the merging rules that combine config files, environment variables, and CLI flags into a single resolved view.
3. Command implementations. crates/uv/src/commands/ contains one module per command family (pip/, project/, python/, tool/, auth/, workspace/, plus standalone files for publish, venv, cache_*, build_frontend, self_update, …).

The crate also owns the user-facing output abstraction (Printer in crates/uv/src/printer.rs), the in-process child-process runner used by uv run (crates/uv/src/child.rs), and the logging setup (crates/uv/src/logging.rs).

Directory layout

crates/uv/
├── Cargo.toml                # Binary crate, depends on virtually every uv-* library
├── build.rs                  # Build-time setup (e.g., embedding manifests on Windows)
├── src/
│   ├── lib.rs                # Top-level run loop, command dispatch, project discovery
│   ├── settings.rs           # Per-command settings structs + merging rules
│   ├── printer.rs            # Stdout/stderr stream abstraction (anstream-aware)
│   ├── logging.rs            # tracing-subscriber setup, durations export
│   ├── child.rs              # Subprocess runner used by `uv run`
│   ├── install_source.rs     # Records how uv was installed (for `uv self update`)
│   └── commands/
│       ├── mod.rs            # Command re-exports + shared helpers (compile_bytecode, OutputWriter)
│       ├── auth/             # `uv auth` namespace (login/logout/token/dir/helper)
│       ├── pip/              # `uv pip {compile,install,sync,uninstall,list,show,tree,freeze,check}`
│       ├── project/          # `uv {init,add,remove,lock,sync,run,export,version,tree,audit,format}`
│       ├── python/           # `uv python {install,find,list,pin,uninstall,update-shell,dir}`
│       ├── tool/             # `uv tool {install,run,list,uninstall,upgrade,update-shell,dir}`
│       ├── workspace/        # `uv workspace {list,metadata,dir}`
│       ├── build_frontend.rs # `uv build` (drives uv-build-frontend)
│       ├── build_backend.rs  # `uv build-backend` (the dev wrapper for uv-build-backend)
│       ├── cache_clean.rs    # `uv cache clean`
│       ├── cache_dir.rs      # `uv cache dir`
│       ├── cache_prune.rs    # `uv cache prune`
│       ├── cache_size.rs     # `uv cache size`
│       ├── help.rs           # `uv help <topic>` long-form help renderer
│       ├── publish.rs        # `uv publish`
│       ├── pylock.rs         # Pylock TOML emission for `uv export --format pylock.toml`
│       ├── reporters.rs      # Progress reporters used by the resolver/installer
│       ├── self_update.rs    # `uv self update`
│       ├── diagnostics.rs    # User-friendly diagnostics formatting
│       └── venv.rs           # `uv venv`
└── tests/
    └── it/                   # Integration tests; the largest source files in the repo live here

Key abstractions

Symbol	File	Purpose
run	crates/uv/src/lib.rs	Top-level async entry point. Calls into a specific command after preview/working-dir/project-dir resolution.
Cli, Commands, ProjectCommand, PipCommand, ToolCommand, …	re-exported from uv-cli	The Clap argument types.
GlobalSettings, CacheSettings, PipInstallSettings, …	crates/uv/src/settings.rs	Resolved settings per command, produced by merging CLI args, environment, project config, and user config.
Printer	crates/uv/src/printer.rs	Owns stdout/stderr streams with color/quiet handling. Most command code writes through printer.stderr()/printer.stdout().
ExitStatus	crates/uv/src/commands/mod.rs	Mirror of process exit codes (Success = 0, Failure = 1, Error = 2, External(u8) for uv run).
ChangeEvent, ChangeEventKind	crates/uv/src/commands/mod.rs	The "package added/removed/reinstalled" diff used by install summaries.
compile_bytecode	crates/uv/src/commands/mod.rs	Helper that drives uv-installer::compile_tree after an install.
ParsedRunCommand, RunCommand	crates/uv/src/commands/project/run.rs	The parsed argument vector for uv run, including module/script/gui-script handling and PEP 723 detection.

How it works

A simplified end-to-end flow for uv add requests:

sequenceDiagram
    participant User
    participant Bin as uv (main.rs)
    participant Cli as uv-cli (Clap)
    participant Run as src/lib.rs::run
    participant Settings as settings.rs
    participant Cmd as commands/project/add.rs
    participant Resolver as uv-resolver
    participant Installer as uv-installer
    User->>Bin: $ uv add requests
    Bin->>Cli: parse argv
    Cli-->>Bin: Cli { command, top_level }
    Bin->>Run: async run(cli)
    Run->>Run: resolve preview, working dir, project dir
    Run->>Run: setup logging (tracing-subscriber)
    Run->>Settings: resolve_settings(...)
    Settings-->>Run: AddSettings (typed)
    Run->>Cmd: commands::add(...)
    Cmd->>Resolver: resolve(workspace, requirements, ...)
    Resolver-->>Cmd: ResolverOutput + Lock
    Cmd->>Installer: install(plan, venv, ...)
    Installer-->>Cmd: InstallationReport
    Cmd-->>Run: ExitStatus
    Run-->>Bin: ExitStatus
    Bin->>User: exit code + stdout/stderr

Settings resolution

settings.rs defines a struct per command (e.g., PipInstallSettings, AddSettings, SyncSettings). Each struct's resolve constructor takes:

• The Clap-parsed args.
• The FilesystemOptions (parsed pyproject.toml + uv.toml).
• EnvironmentOptions (parsed environment variables).
• GlobalSettings and CacheSettings.

The Combine trait (defined in uv-settings) merges in priority order: CLI

environment > project config > user config > defaults. The --show-settings global flag prints the resolved struct for debugging.

Command modules

Each module under commands/ exposes a top-level pub(crate) async fn that takes the resolved settings and a few orchestrator handles (Cache, Printer, Concurrency, …). The pattern is consistent: do any preliminary setup (workspace discovery, venv creation), call into the relevant library crate, format the result.

For project commands, most of the heavy lifting is shared in commands/project/mod.rs (a 110 KB file) with helpers like do_lock, do_sync, and do_install. Per-command modules (add.rs, remove.rs, sync.rs, lock.rs, …) call those helpers after their command-specific TOML edits.

uv run and child processes

commands/project/run.rs (~83 KB) is the most complex command. It:

1. Detects whether the argument is a Python module, file, URL, GUI script, - (stdin), or a regular command.
2. If it's a PEP 723 script, parses inline metadata via uv-scripts.
3. Discovers the workspace (or, with the target-workspace-discovery preview flag, the script's own workspace).
4. Syncs the environment (calling into commands/project/sync.rs).
5. Spawns the target via crates/uv/src/child.rs::run, which sets up signal forwarding and inherits stdout/stderr.

Integration points

This crate is the only crate that depends directly on every public uv library. The reverse is also true: no library depends on uv. That keeps the dependency graph clean and lets individual crates be unit-tested without dragging in the binary.

The notable shared abstractions injected from this crate into libraries via traits (defined in uv-types) are:

• BuildContext — implemented in crates/uv/src/commands/ to give the resolver a way to build sdists during resolution.
• InstalledPackagesProvider — supplied by the binary so the resolver can prefer already-installed versions.
• The progress reporters in crates/uv/src/commands/reporters.rs implement the various Reporter traits exposed by the resolver, installer, preparer, and Python downloader.

Entry points for modification

• Adding a new subcommand — add a variant to the relevant enum in crates/uv-cli/src/lib.rs, add a settings struct in crates/uv/src/settings.rs, add a module in crates/uv/src/commands/<family>/, and dispatch from crates/uv/src/lib.rs::run.
• Adding a configuration option — extend the relevant Options struct in uv-settings, update settings.rs to merge it, and (for user-visible options) regenerate the JSON schema with cargo dev generate-all.
• Changing output format — Printer is the place. For new structured output, add a JSON variant to the relevant settings struct (most commands already accept --format json) and emit through OutputWriter in crates/uv/src/commands/mod.rs.
• New global flag — add it to GlobalArgs in crates/uv-cli/src/lib.rs and thread it through GlobalSettings in crates/uv/src/settings.rs.

Key source files

File	Purpose
crates/uv/src/lib.rs	Top-level run loop, command dispatch, working-directory and project-directory resolution.
crates/uv/src/settings.rs	Per-command resolved settings and merging logic.
crates/uv/src/commands/mod.rs	Command re-exports, ExitStatus, OutputWriter, compile_bytecode helper.
crates/uv/src/commands/project/mod.rs	Shared do_lock / do_sync / do_install helpers used by add/remove/lock/sync.
crates/uv/src/commands/project/run.rs	uv run argument parsing, PEP 723 detection, child spawning.
crates/uv/src/printer.rs	The Printer abstraction.
crates/uv/src/logging.rs	tracing-subscriber configuration and RUST_LOG parsing.
crates/uv/src/child.rs	Subprocess runner with signal handling.

See also

• uv-cli — the argument schema this crate dispatches on.
• uv-settings — the underlying uv.toml model.
• features/project-workflow — a walk-through of uv init → uv add → uv lock → uv sync → uv run.