# Understanding the uv Monorepo Structure: A Guide to Its 70+ Rust Crates

> Explore the uv monorepo structure and its 70+ Rust crates. Learn how Cargo workspaces streamline shared dependencies, feature flags, and incremental builds for efficient development.

- Repository: [Astral/uv](https://github.com/astral-sh/uv)
- Tags: internals
- Published: 2026-03-01

---

**The uv monorepo uses a Cargo workspace to organize approximately 70 internal crates under a unified `crates/` directory, enabling shared dependencies, coordinated feature flags, and incremental builds across the entire project.**

The **uv** repository from Astral is a high-performance Python package manager written in Rust. Its monorepo structure relies on a single Cargo workspace defined in the root [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml) to manage internal dependencies and versioning across dozens of specialized crates.

## Why uv Uses a Cargo Workspace for Its Monorepo Structure

A Cargo workspace allows uv to treat multiple crates as a single unit while preserving modularity. The root [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml) declares `members = ["crates/*"]`, which automatically includes all directories under `crates/` except those explicitly excluded (such as `crates/uv-trampoline` and the `scripts/` directory).

This design delivers several advantages:

- **Unified versioning** – The `[workspace.package]` table defines shared metadata (`edition`, `rust-version`, `license`, `authors`) that every crate inherits, ensuring consistency across the monorepo.
- **Centralized dependencies** – The `[workspace.dependencies]` table (lines 18‑79 in the root [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml)) pins versions for roughly 70 internal crates (typically `0.0.27`). Sub‑crates reference these via `{ workspace = true }`, guaranteeing lockstep updates.
- **Feature coordination** – Flags like `performance`, `self-update`, and `test-defaults` are declared once in the root and propagated to dependent crates. For example, the `performance` feature enables `uv-performance-memory-allocator` across the workspace.
- **Incremental builds** – Cargo caches unchanged crates while rebuilding only modified ones, reducing compile times during development.

## How the uv Monorepo Organizes ~70 Crates

All production code resides under the `crates/` directory. The workspace currently manages approximately 70 internal crates, categorized by responsibility:

### Core Engine and CLI

- **`uv`** – The primary library exposing the high‑level API ([`crates/uv/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv/src/lib.rs)).
- **`uv-cli`** – Implements the command‑line binary (`uv` and `uvw` commands).
- **`uv-workspace`** – Workspace utilities and cargo‑dist integration.

### Dependency Resolution

- **`uv-resolver`** – The core resolution engine implementing version solving.
- **`uv-requirements`** and **`uv-requirements-txt`** – Parse [`requirements.txt`](https://github.com/astral-sh/uv/blob/main/requirements.txt) and PEP 508 requirements.
- **`uv-pep440`** and **`uv-pep508`** – Python packaging standard parsers.

### Packaging and Distribution

- **`uv-distribution`**, **`uv-distribution-types`**, **`uv-distribution-filename`** – Handle wheel and source distribution metadata.
- **`uv-install-wheel`** – Wheel installation logic.
- **`uv-publish`** – PyPI upload functionality.

### Environment and Python Handling

- **`uv-virtualenv`** – Virtual environment creation and management.
- **`uv-python`** – Interpreter discovery and Python version handling.
- **`uv-settings`** and **`uv-configuration`** – Configuration file parsing.

### Platform and I/O Utilities

- **`uv-fs`**, **`uv-dirs`**, **`uv-extract`**, **`uv-globfilter`** – File system operations, archive extraction, and glob matching.
- **`uv-unix`**, **`uv-windows`**, **`uv-platform`** – OS‑specific abstractions.
- **`uv-git`**, **`uv-git-types`**, **`uv-auth`** – Git operations and authentication (SSH, tokens).

### Tooling and Performance

- **`uv-tool`** – CLI scaffolding helpers.
- **`uv-bench`** – Benchmark harness.
- **`uv-performance-memory-allocator`** – Optional high‑performance allocator (enabled via `performance` feature).
- **`uv-trampoline-builder`** – Self‑update trampoline logic (excluded from default builds).

## Key Configuration Files in the uv Monorepo Structure

Understanding the workspace requires familiarity with these specific files:

- **[`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml)** (root) – Defines the workspace members, shared metadata, and the `[workspace.dependencies]` table containing all ~70 internal crates.
- **[`crates/uv/Cargo.toml`](https://github.com/astral-sh/uv/blob/main/crates/uv/Cargo.toml)** – The main library manifest that re‑exports functionality from sub‑crates.
- **[`crates/uv-cli/Cargo.toml`](https://github.com/astral-sh/uv/blob/main/crates/uv-cli/Cargo.toml)** – Defines the binary targets `uv` and `uvw`.
- **[`crates/uv-resolver/Cargo.toml`](https://github.com/astral-sh/uv/blob/main/crates/uv-resolver/Cargo.toml)** and **[`crates/uv-distribution/Cargo.toml`](https://github.com/astral-sh/uv/blob/main/crates/uv-distribution/Cargo.toml)** – Core algorithmic crates with heavy feature gating.
- **`it/`** – Integration test directory containing cross‑crate tests that rely on the `test-defaults` feature flag.

## Working with the uv Monorepo: Practical Examples

### Using the uv Library in an External Rust Project

You can depend on individual crates or the main `uv` crate:

```toml
[dependencies]
uv = { version = "0.10.7", features = ["performance"] }

```

```rust
// src/main.rs
use uv::resolver::Resolver;
use uv::python::{PythonEnvironment, Interpreter};

fn main() -> anyhow::Result<()> {
    // Detect the active Python interpreter
    let env = PythonEnvironment::default()?;
    let interpreter = Interpreter::find(&env)?;

    // Resolve a simple requirement (e.g., "requests>=2.0")
    let resolver = Resolver::new(&env);
    let result = resolver.resolve_requirements(&["requests>=2.0"])?;
    println!("Resolved packages: {:#?}", result);

    Ok(())
}

```

*Source:* `uv` crate implementation – [[`crates/uv/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv/src/lib.rs)](https://github.com/astral-sh/uv/blob/main/crates/uv/src/lib.rs).

### Running the uv CLI Programmatically

```rust
use uv_cli::run_cli;
use std::env;

fn main() {
    // Simulate a `uv install` command
    let args = vec!["uv".to_string(), "install".to_string()];
    env::set_var("UV_LOG", "info");
    // `run_cli` returns an exit code
    let code = run_cli(args);
    std::process::exit(code);
}

```

*Source:* CLI entry point – [[`crates/uv-cli/src/main.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-cli/src/main.rs)](https://github.com/astral-sh/uv/blob/main/crates/uv-cli/src/main.rs).

### Adding a New Internal Crate

To extend the monorepo with a new library:

```bash

# Create a new crate folder

cargo new --lib crates/uv-example

```

Then update the root [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml) to include it in the workspace dependencies:

```toml
[workspace.dependencies]
uv-example = { version = "0.0.27", path = "crates/uv-example" }

```

Sub‑crates can then reference it via:

```toml
[dependencies]
uv-example = { workspace = true }

```

*Source:* Workspace configuration – [[`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml)](https://github.com/astral-sh/uv/blob/main/Cargo.toml) lines 18‑79.

## Summary

- The **uv monorepo structure** relies on a single Cargo workspace defined in the root [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml) with `members = ["crates/*"]`.
- Approximately **70 internal crates** live under `crates/`, organized by domain (resolution, distribution, Python handling, platform abstractions).
- **Unified versioning** and **shared dependencies** are managed through `[workspace.package]` and `[workspace.dependencies]`, ensuring all crates stay synchronized at version `0.0.27`.
- **Feature flags** like `performance` and `self-update` are coordinated at the workspace level and propagated to individual crates.
- The `uv` crate serves as the main library entry point, while `uv-cli` provides the binary executable.

## Frequently Asked Questions

### How many crates are in the uv monorepo?

The uv repository contains approximately **70 internal crates** managed under a single Cargo workspace. These crates are defined in the `[workspace.dependencies]` table of the root [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml) and physically reside in the `crates/` directory.

### What is the purpose of the crates/ directory in uv?

The `crates/` directory houses all production code in the uv monorepo structure. Each subdirectory represents an individual Rust crate with a specific responsibility—such as `uv-resolver` for dependency resolution or `uv-python` for interpreter management—allowing the project to maintain modularity while sharing a unified build configuration.

### How does uv manage dependencies across its monorepo crates?

uv uses **workspace-level dependency management** via the `[workspace.dependencies]` table in the root [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml). All internal crates reference dependencies using `{ workspace = true }`, which ensures they use the same version (currently `0.0.27` for most internal crates) and stay synchronized during updates.

### Can I use individual uv crates in my own Rust project?

Yes, you can depend on specific uv crates or the main `uv` library by adding them to your [`Cargo.toml`](https://github.com/astral-sh/uv/blob/main/Cargo.toml) with the desired features. For example, you can import `uv-resolver` for Python dependency resolution logic or `uv-python` for interpreter discovery, though you should check each crate's public API stability as uv is rapidly evolving.