# astral-sh/uv architecture

> Architecture diagram of the GitHub repository astral-sh/uv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astral-sh/uv
- Repository: https://github.com/astral-sh/uv
- Video tour (about a minute): https://gitdiagram.com/astral-sh/uv/video

## Overview

uv is a Rust-based Python package and project manager. The principal workflow starts at its CLI, resolves project or requirements inputs, obtains package metadata and distributions, then installs them into a managed environment; projects can also persist resolutions in a universal lockfile. Separate command branches support pip compatibility, scripts and tools, Python-version management, building/publishing, and auditing. The graph follows documented capabilities and crate responsibilities; sampled implementation excerpts are limited, so uncertain internal call wiring is omitted.

Main entry points: [`crates/uv/src/bin/uv.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv/src/bin/uv.rs) (uv CLI), [`crates/uv/src/commands/project/mod.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/mod.rs) (Project commands), [`crates/uv-resolver/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-resolver/src/lib.rs) (Dependency resolver), [`crates/uv-client/src/registry_client.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-client/src/registry_client.rs) (Registry client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and projects"]
  node_cli["uv CLI<br/>[uv.rs]"]
  node_project["Project commands<br/>[mod.rs]"]
  node_project_sync["Project sync<br/>[sync.rs]"]
  node_pip["pip commands<br/>[mod.rs]"]
  node_lock["Lockfile<br/>[lib.rs]"]
  node_workspace["Workspace<br/>[lib.rs]"]
end

subgraph group_resolve["Resolution and artifacts"]
  node_resolver["Dependency resolver<br/>[lib.rs]"]
  node_distribution["Distribution database"]
  node_installer["Package installer<br/>[lib.rs]"]
end

subgraph group_env["Environments and tools"]
  node_environment["Virtual environments<br/>[lib.rs]"]
  node_script["Script execution<br/>[run.rs]"]
  node_tool["Tool management<br/>[mod.rs]"]
  node_python["Python management<br/>[mod.rs]"]
  node_build["Build backend<br/>[lib.rs]"]
  node_publish["Publish command<br/>[publish.rs]"]
  node_audit["Dependency audit<br/>[audit.rs]"]
end

subgraph group_services["Package services"]
  node_registry["Registry client<br/>[registry_client.rs]"]
  node_cache[("Global cache<br/>[lib.rs]")]
end

node_user(("User"))
node_pypi[("Python package index")]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_project
node_cli -->|"dispatches"| node_pip
node_cli -->|"dispatches"| node_tool
node_cli -->|"dispatches"| node_python
node_project -->|"reads project"| node_workspace
node_project -->|"syncs project"| node_project_sync
node_project_sync -->|"resolves dependencies"| node_resolver
node_project_sync -->|"installs packages"| node_installer
node_project -->|"writes lockfile"| node_lock
node_pip -->|"resolves requirements"| node_resolver
node_pip -->|"installs packages"| node_installer
node_resolver -->|"requests metadata"| node_registry
node_registry -->|"fetches index data"| node_pypi
node_distribution -->|"fetches metadata"| node_registry
node_distribution -->|"downloads distributions"| node_pypi
node_distribution -->|"caches artifacts"| node_cache
node_installer -->|"installs into"| node_environment
node_script -->|"runs in"| node_environment
node_tool -->|"resolves tool"| node_resolver
node_tool -->|"manages tool environment"| node_environment
node_python -->|"selects interpreter"| node_environment
node_publish -->|"builds artifacts"| node_build
node_publish -->|"publishes packages"| node_pypi
node_audit -->|"checks package status"| node_registry

click node_cli "https://github.com/astral-sh/uv/blob/main/crates/uv/src/bin/uv.rs"
click node_project "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/mod.rs"
click node_project_sync "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/sync.rs"
click node_pip "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/pip/mod.rs"
click node_lock "https://github.com/astral-sh/uv/blob/main/crates/uv-lock/src/lib.rs"
click node_workspace "https://github.com/astral-sh/uv/blob/main/crates/uv-workspace/src/lib.rs"
click node_resolver "https://github.com/astral-sh/uv/blob/main/crates/uv-resolver/src/lib.rs"
click node_registry "https://github.com/astral-sh/uv/blob/main/crates/uv-client/src/registry_client.rs"
click node_distribution "https://github.com/astral-sh/uv/blob/main/crates/uv-distribution/src/distribution_database.rs"
click node_installer "https://github.com/astral-sh/uv/blob/main/crates/uv-installer/src/lib.rs"
click node_cache "https://github.com/astral-sh/uv/blob/main/crates/uv-cache/src/lib.rs"
click node_environment "https://github.com/astral-sh/uv/blob/main/crates/uv-virtualenv/src/lib.rs"
click node_script "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/run.rs"
click node_tool "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/tool/mod.rs"
click node_python "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/python/mod.rs"
click node_build "https://github.com/astral-sh/uv/blob/main/crates/uv-build-backend/src/lib.rs"
click node_publish "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/publish.rs"
click node_audit "https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/audit.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_project,node_project_sync,node_pip,node_lock,node_workspace,node_user toneBlue
class node_resolver,node_distribution,node_installer,node_pypi toneAmber
class node_environment,node_script,node_tool,node_python,node_build,node_publish,node_audit toneMint
class node_registry,node_cache toneRose
```

## Components

### CLI and projects

- [uv CLI](https://github.com/astral-sh/uv/blob/main/crates/uv/src/bin/uv.rs): `crates/uv/src/bin/uv.rs`
- [Project commands](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/mod.rs): `crates/uv/src/commands/project/mod.rs`
- [Project sync](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/sync.rs): `crates/uv/src/commands/project/sync.rs`
- [pip commands](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/pip/mod.rs): `crates/uv/src/commands/pip/mod.rs`
- [Lockfile](https://github.com/astral-sh/uv/blob/main/crates/uv-lock/src/lib.rs): `crates/uv-lock/src/lib.rs`
- [Workspace](https://github.com/astral-sh/uv/blob/main/crates/uv-workspace/src/lib.rs): `crates/uv-workspace/src/lib.rs`

### Resolution and artifacts

- [Dependency resolver](https://github.com/astral-sh/uv/blob/main/crates/uv-resolver/src/lib.rs): `crates/uv-resolver/src/lib.rs`
- [Distribution database](https://github.com/astral-sh/uv/blob/main/crates/uv-distribution/src/distribution_database.rs): `crates/uv-distribution/src/distribution_database.rs`
- [Package installer](https://github.com/astral-sh/uv/blob/main/crates/uv-installer/src/lib.rs): `crates/uv-installer/src/lib.rs`

### Environments and tools

- [Virtual environments](https://github.com/astral-sh/uv/blob/main/crates/uv-virtualenv/src/lib.rs): `crates/uv-virtualenv/src/lib.rs`
- [Script execution](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/run.rs): `crates/uv/src/commands/project/run.rs`
- [Tool management](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/tool/mod.rs): `crates/uv/src/commands/tool/mod.rs`
- [Python management](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/python/mod.rs): `crates/uv/src/commands/python/mod.rs`
- [Build backend](https://github.com/astral-sh/uv/blob/main/crates/uv-build-backend/src/lib.rs): `crates/uv-build-backend/src/lib.rs`
- [Publish command](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/publish.rs): `crates/uv/src/commands/publish.rs`
- [Dependency audit](https://github.com/astral-sh/uv/blob/main/crates/uv/src/commands/project/audit.rs): `crates/uv/src/commands/project/audit.rs`

### Package services

- [Registry client](https://github.com/astral-sh/uv/blob/main/crates/uv-client/src/registry_client.rs): `crates/uv-client/src/registry_client.rs`
- [Global cache](https://github.com/astral-sh/uv/blob/main/crates/uv-cache/src/lib.rs): `crates/uv-cache/src/lib.rs`

### Other components

- **User**
- **Python package index**

## Connections

- User → uv CLI: invokes
- uv CLI → Project commands: dispatches
- uv CLI → pip commands: dispatches
- uv CLI → Tool management: dispatches
- uv CLI → Python management: dispatches
- Project commands → Workspace: reads project
- Project commands → Project sync: syncs project
- Project sync → Dependency resolver: resolves dependencies
- Project sync → Package installer: installs packages
- Project commands → Lockfile: writes lockfile
- pip commands → Dependency resolver: resolves requirements
- pip commands → Package installer: installs packages
- Dependency resolver → Registry client: requests metadata
- Registry client → Python package index: fetches index data
- Distribution database → Registry client: fetches metadata
- Distribution database → Python package index: downloads distributions
- Distribution database → Global cache: caches artifacts
- Package installer → Virtual environments: installs into
- Script execution → Virtual environments: runs in
- Tool management → Dependency resolver: resolves tool
- Tool management → Virtual environments: manages tool environment
- Python management → Virtual environments: selects interpreter
- Publish command → Build backend: builds artifacts
- Publish command → Python package index: publishes packages
- Dependency audit → Registry client: checks package status
