astral-sh/uv

Configuration

uv's configuration model layers six sources, in order of precedence (highest first):

Layers are merged via the Combine trait in uv-settings.

Top-level tables

Table	Where	Purpose
`[tool.uv]`	`pyproject.toml`	Per-project uv settings.
`[tool.uv.sources]`	`pyproject.toml`	Override source location for a dependency (path, git, URL).
`[[tool.uv.index]]`	`pyproject.toml` / `uv.toml`	Named indexes, with priority.
`[tool.uv.workspace]`	`pyproject.toml`	Workspace members + exclusions.
`[tool.uv.environments]`	`pyproject.toml`	Required marker environments.
`[tool.uv.required-environments]`	`pyproject.toml`	Mandatory environments to resolve for.
`[tool.uv.conflicts]`	`pyproject.toml`	Mutually-exclusive extras / groups.
`[tool.uv.dependency-groups]`	`pyproject.toml`	Group inclusions and defaults (PEP 735).
`[tool.uv.dependency-metadata]`	`pyproject.toml`	Per-dependency metadata overrides.
`[tool.uv.build-backend]`	`pyproject.toml`	Settings for the uv-build backend.
`[tool.uv.pip]`	`uv.toml`	`uv pip` legacy compatibility settings.
`[tool.uv.publish]`	`uv.toml`	Default index for publishing.

The full schema, with every field documented and typed, is generated from uv-settings into uv.schema.json.

The canonical list is generated from uv-static via cargo dev generate-env-vars-reference. Categories include:

Cache / state — UV_CACHE_DIR, UV_STATE_DIR, UV_CONFIG_DIR.
Indexes — UV_INDEX_URL, UV_EXTRA_INDEX_URL, UV_INDEX_<NAME>_*.
Auth — UV_KEYRING_PROVIDER, UV_PUBLISH_USERNAME, UV_PUBLISH_PASSWORD.
Behavior — UV_OFFLINE, UV_NO_CACHE, UV_NO_BUILD_ISOLATION, UV_PREVIEW.
Concurrency — UV_CONCURRENT_DOWNLOADS, UV_CONCURRENT_INSTALLS, UV_CONCURRENT_BUILDS.
Logging — RUST_LOG, UV_LOG_FILE, UV_NO_PROGRESS.