Settings and Configuration

Relevant source files

• crates/uv-cli/Cargo.toml
• crates/uv-cli/build.rs
• crates/uv-cli/src/lib.rs
• crates/uv-configuration/src/target_triple.rs
• crates/uv-preview/src/lib.rs
• crates/uv-settings/Cargo.toml
• crates/uv-settings/src/combine.rs
• crates/uv-settings/src/lib.rs
• crates/uv-settings/src/settings.rs
• crates/uv-static/src/env_vars.rs
• crates/uv/src/commands/mod.rs
• crates/uv/src/lib.rs
• crates/uv/src/settings.rs
• crates/uv/tests/it/help.rs
• crates/uv/tests/sync/show_settings.rs
• docs/concepts/preview.md
• uv.schema.json

This document describes uv's configuration system, which allows users to customize behavior through configuration files, environment variables, and command-line arguments. The system implements a six-layer precedence hierarchy that merges settings from multiple sources using the Combine trait to produce a unified runtime configuration.

For detailed workspace discovery and project metadata handling, see 7.4 Workspace Support For command-line parsing and argument flow, see 2.1 CLI Architecture and Parsing

---

Configuration Hierarchy

uv loads and merges configuration from six hierarchical sources, applied in order of increasing precedence (lowest to highest):

1. System Configuration — e.g., /etc/uv/uv.toml crates/uv-settings/src/lib.rs75-88
2. User Configuration — e.g., ~/.config/uv/uv.toml crates/uv-settings/src/lib.rs47-73
3. Project Configuration — from uv.toml or [tool.uv] in pyproject.toml crates/uv-settings/src/lib.rs94-118
4. Script Metadata — inline PEP 723 metadata in Python scripts crates/uv/src/lib.rs151-152
5. Environment Variables — typically prefixed with UV_ crates/uv-static/src/env_vars.rs1-130
6. Command-Line Arguments — explicit CLI flags passed at runtime crates/uv-cli/src/lib.rs120-136

Each source's options override or extend those of a lower-priority source, enabling flexible and precise user control.

Configuration Hierarchy Diagram

Sources: crates/uv/src/lib.rs113-154 crates/uv/src/settings.rs97-162 crates/uv-settings/src/lib.rs27-154

---

Discovery and Loading Process

The process of locating configuration files and environment variables follows these steps:

1. Explicit Config Path: If the user provides --config-file or sets UV_CONFIG_FILE, uv loads that file exclusively crates/uv-cli/src/lib.rs147-158
2. Project Config Discovery: uv searches upward from the current directory for a uv.toml or a pyproject.toml containing [tool.uv] crates/uv-settings/src/lib.rs94-118
3. User Config: uv loads user-level configuration from standard platform config directories via user_config_dir() crates/uv-settings/src/lib.rs47-52
4. System Config: uv loads system-wide configuration files at standard locations via system_config_file() crates/uv-settings/src/lib.rs75-81

The global no-config flag (--no-config or UV_NO_CONFIG) disables automatic config discovery crates/uv-cli/src/lib.rs160-165 crates/uv-static/src/env_vars.rs75-78

Sources: crates/uv/src/lib.rs113-115 crates/uv-settings/src/lib.rs47-154 crates/uv-cli/src/lib.rs140-166

---

Configuration File Formats

uv.toml

• Dedicated TOML file specifying uv configuration crates/uv-settings/src/lib.rs124-137
• If found alongside pyproject.toml, it masks the [tool.uv] section in pyproject.toml crates/uv-settings/src/lib.rs141-150

pyproject.toml [tool.uv]

• Optional configuration inside the PEP 621/517 pyproject.toml crates/uv-settings/src/settings.rs35-47
• Supports standard dependencies in [project] and uv-specific overrides in [tool.uv] crates/uv-settings/src/settings.rs75-83

Sources: crates/uv-settings/src/settings.rs35-83 crates/uv-settings/src/lib.rs120-182

---

Settings Structures and Flow

uv represents settings with multiple Rust structs that reflect layers in configuration and progressively merge them.

Mapping Natural Language Configuration to Code Entities

• FilesystemOptions: Wraps Options loaded from disk with an Origin (System, User, or Project) crates/uv-settings/src/lib.rs27-28
• EnvironmentOptions: Captures environment-specific overrides like concurrency and log context crates/uv/src/lib.rs152
• GlobalSettings: The final runtime structure used by commands to access resolved values for color, preview, and Python preferences crates/uv/src/settings.rs80-93

Sources: crates/uv/src/settings.rs79-162 crates/uv-settings/src/lib.rs27-43 crates/uv-settings/src/settings.rs75-101

---

The Combine Trait: Layered Settings Merging

The core concept enabling hierarchical configuration precedence is the Combine trait.

• Trait Signature: fn combine(self, other: Self) -> Self; crates/uv-settings/src/combine.rs28-42
• Logic: self (higher priority) is merged with other (lower priority) crates/uv-settings/src/combine.rs29-39
• Implementation: For Option<T>, it generally returns self if Some, otherwise other crates/uv-settings/src/combine.rs84-128

Common Merge Semantics

Type	Merge Behavior
Option<T>	Returns self if Some, else other crates/uv-settings/src/combine.rs84-128
Option<Vec<T>>	Concatenates vectors: self elements followed by other elements crates/uv-settings/src/combine.rs129-141
BTreeMap<K, Vec<T>>	Merges maps by combining their vectors for matching keys crates/uv-settings/src/combine.rs143-156
ConfigSettings	Merges PEP 517 build settings maps crates/uv-settings/src/combine.rs174-183

Combine Trait Diagram

Sources: crates/uv-settings/src/combine.rs28-213

---

Runtime Global Settings Resolution

At runtime, GlobalSettings::resolve computes effective settings crates/uv/src/settings.rs97-162

• Concurrency: Merges environment variables, workspace settings, and defaults for downloads, builds, and installs crates/uv/src/settings.rs112-136
• Python Downloads: Combines CLI flags (--allow-python-downloads), environment variables (UV_PYTHON_DOWNLOADS), and workspace config crates/uv/src/settings.rs140-148
• Preview: Resolved early to handle decisions affecting config discovery roots and globally set via uv_preview::set crates/uv/src/lib.rs154-159

Resolution Flow Diagram

Sources: crates/uv/src/settings.rs97-162 crates/uv/src/lib.rs113-159 crates/uv-cli/src/lib.rs178-211

---

Environment Variables Overview

uv supports a rich ecosystem of environment variables mapped via the EnvVars struct crates/uv-static/src/env_vars.rs6-9

Examples of Key Environment Variables

Variable	Description	Source
UV_CONFIG_FILE	Path to a uv.toml file to use for configuration.	crates/uv-static/src/env_vars.rs148
UV_NO_CONFIG	Avoid discovering configuration files.	crates/uv-static/src/env_vars.rs155
UV_PYTHON	Equivalent to the --python command-line argument.	crates/uv-static/src/env_vars.rs107
UV_SYSTEM_PYTHON	Equivalent to the --system command-line argument.	crates/uv-static/src/env_vars.rs102
UV_OFFLINE	Equivalent to the --offline command-line argument.	crates/uv-static/src/env_vars.rs32
UV_CACHE_DIR	Equivalent to the --cache-dir command-line argument.	crates/uv-static/src/env_vars.rs69
RUFF	Path to the Ruff binary used by uv format.	crates/uv-static/src/env_vars.rs24
TY	Path to the ty binary used by uv check.	crates/uv-static/src/env_vars.rs28

Sources: crates/uv-static/src/env_vars.rs1-130 crates/uv-cli/src/lib.rs151-165

---

Configuration JSON Schema

uv uses a JSON schema to define the structure of Options and GlobalOptions uv.schema.json3-6

• cache-keys: Defines how builds are invalidated based on files, git state, or environment uv.schema.json57-63
• add-bounds: Configures default version specifiers (e.g., >=1.2.3) when adding dependencies uv.schema.json7-17
• concurrent-builds/downloads/installs: Fine-grained control over parallel operations uv.schema.json79-96
• config-settings: Settings to pass to PEP 517 build backends uv.schema.json97-101

Sources: uv.schema.json1-102