uv-settings

crates/uv-settings/ is the home of uv's configuration model — the uv.toml schema, the [tool.uv] table that complements it, and the merging logic that combines user, project, and environment values into a single Options view.

Purpose

uv has a layered configuration system: defaults, user ~/.config/uv/uv.toml, project uv.toml and pyproject.toml, environment variables, CLI flags. This crate defines:

• The Options struct (the full schema).
• The FilesystemOptions discovery / parsing.
• The EnvironmentOptions parser.
• The Combine trait that lets the binary merge in priority order.
• The Python install mirrors and other shared constants.

Directory layout

crates/uv-settings/src/
├── lib.rs              # Re-exports
├── settings.rs         # Options, ToolOptions, RegistryOptions: the typed schema
├── combine.rs          # The Combine trait and impls
├── environment.rs      # EnvironmentOptions: env-var parsing
├── fs.rs               # FilesystemOptions: discovering uv.toml + pyproject.toml on disk
└── ...                 # Per-area submodules (mirrors, cache, …)

Key abstractions

Type	Role
Options	The merged, typed configuration view used by every uv command. Mirrors the uv.toml/[tool.uv] schema.
FilesystemOptions	Reads, validates, and merges configuration from disk. Walks parent directories looking for uv.toml and pyproject.toml.
EnvironmentOptions	Parses environment variables (UV_*) into a partial Options.
Combine	Trait fn combine(self, other: Self) -> Self — defines the priority for each field.
PythonInstallMirrors	The mirror configuration for managed Python downloads.

How it works

The binary's crates/uv/src/lib.rs::run builds the merged config in priority order:

defaults → user uv.toml → project uv.toml → project pyproject.toml [tool.uv] → env vars → CLI flags

Combine is implemented for every field, with the rule "prefer the higher-priority value if present, otherwise fall back to the lower-priority value." Lists merge by concatenation; maps merge by union with overrides.

The output drives crates/uv/src/settings.rs, which converts Options into per-command typed structs.

Integration points

• uv is the only consumer; this crate has no dependencies on resolver/installer.
• uv-options-metadata generates the JSON schema from Options.

Key source files

File	Purpose
crates/uv-settings/src/settings.rs	The schema.
crates/uv-settings/src/combine.rs	Merging rules.
crates/uv-settings/src/fs.rs	Discovery on disk.
crates/uv-settings/src/environment.rs	Env-var parsing.

See also

• uv-workspace for the pyproject.toml side.
• uv-options-metadata for the JSON schema generator.
• reference/configuration for the full surface.