# uv Configuration Reference

Complete configuration guide for uv (v0.9.5).

## Configuration Files

### File Discovery Hierarchy

1. **Project-level** (current or parent directories):
   - `pyproject.toml` (under `[tool.uv]`)
   - `uv.toml` (no prefix required)

2. **User-level**:
   - Linux/macOS: `~/.config/uv/uv.toml`
   - Windows: `%APPDATA%\uv\uv.toml`

3. **System-level**:
   - Linux/macOS: `/etc/uv/uv.toml`
   - Windows: `%PROGRAMDATA%\uv\uv.toml`

### Precedence Order

1. Command-line arguments (highest)
2. Environment variables
3. Project-level configuration
4. User-level configuration
5. System-level configuration (lowest)

**Note**: `uv.toml` takes precedence over `pyproject.toml` in same directory.

## pyproject.toml Configuration

### Project Metadata

```toml
[project]
name = "myproject"
version = "1.0.0"
description = "Project description"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31",
    "fastapi>=0.115",
]

# Preferred: Use PEP 735 dependency groups
[dependency-groups]
dev = [
    "pytest>=8.4.2",
    "ruff>=0.13.3",
    "mypy>=1.18.2",
]
docs = ["sphinx", "mkdocs"]
test = ["pytest-cov", "hypothesis"]

# Alternative: project.optional-dependencies (older pattern)
# [project.optional-dependencies]
# dev = ["pytest>=8.3", "ruff>=0.5"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

### Core uv Settings

```toml
[tool.uv]
# Project management
managed = true              # uv manages project
package = true              # Project is Python package
default-groups = ["dev"]    # Default dependency groups

# Resolution
resolution = "highest"      # highest/lowest/lowest-direct
fork-strategy = "requires-python"  # requires-python/fewest
index-strategy = "first-index"     # first-index/unsafe-first-match/unsafe-best-match

# Environment restrictions
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
]

# Dependency constraints
constraint-dependencies = ["grpcio<1.65"]
override-dependencies = ["werkzeug==2.3.0"]

# Build configuration
compile-bytecode = true
no-build-isolation-package = ["flash-attn"]
config-settings = { editable_mode = "compat" }

# Cache configuration
cache-dir = "./.uv_cache"
cache-keys = [
    { file = "pyproject.toml" },
    { git = { commit = true } },
]

# Network configuration
concurrent-downloads = 20
concurrent-builds = 8
offline = false

# Python management
python-preference = "managed"  # only-managed/managed/system/only-system
python-downloads = "automatic"  # automatic/manual/never

# Security
keyring-provider = "subprocess"  # subprocess/disabled
allow-insecure-host = ["packages.example.com"]

# Preview features
preview = true
```

### Package Indexes

```toml
[[tool.uv.index]]
name = "pytorch-cu121"
url = "https://download.pytorch.org/whl/cu121"
explicit = true              # Require explicit pinning
default = false              # Replace PyPI as default
authenticate = "always"      # always/never
cache-control = "max-age=3600"

[[tool.uv.index]]
name = "private-registry"
url = "https://packages.example.com/simple"
explicit = true
```

### Dependency Sources

```toml
[tool.uv.sources]
# Workspace dependencies
internal-lib = { workspace = true }

# Git repositories
httpx = { git = "https://github.com/encode/httpx" }
fastapi = { git = "https://github.com/tiangolo/fastapi", branch = "main" }
requests = { git = "https://github.com/psf/requests", tag = "v2.31.0" }

# Local paths
local-pkg = { path = "../local-pkg" }
editable-pkg = { path = "./pkg", editable = true }

# URLs
package-url = { url = "https://example.com/package.tar.gz" }

# Index pinning
torch = { index = "pytorch-cu121" }

# Conditional sources
package = [
    { index = "linux-index", marker = "sys_platform == 'linux'" },
    { index = "macos-index", marker = "sys_platform == 'darwin'" },
]
```

### Workspace Configuration

```toml
[tool.uv.workspace]
members = ["packages/*", "apps/*"]
exclude = ["packages/deprecated"]
```

### Build Configuration

```toml
[tool.uv]
# Build isolation control
no-build-isolation-package = ["flash-attn", "deepspeed"]

# Extra build dependencies
[tool.uv.extra-build-dependencies]
flash-attn = ["torch", "setuptools"]
deepspeed = [{ requirement = "torch", match-runtime = true }]

# Build environment variables
[tool.uv.extra-build-variables]
flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }
opencv-python = { CMAKE_ARGS = "-DWITH_CUDA=ON" }

# Dependency metadata (for packages without proper metadata)
[[tool.uv.dependency-metadata]]
name = "package-name"
version = "1.0.0"
requires-dist = ["dependency1>=1.0"]
requires-python = ">=3.8"

# Per-package build settings
[tool.uv.config-settings-package]
numpy = { editable_mode = "compat" }
scipy = { use_system_blas = "true" }

# Build constraints
build-constraint-dependencies = ["setuptools==60.0.0"]
```

### Conflict Resolution

```toml
[tool.uv]
# Declare mutually exclusive extras/groups
conflicts = [
    [
        { extra = "cuda" },
        { extra = "rocm" },
    ],
    [
        { group = "prod" },
        { group = "dev" },
    ],
]
```

### pip-Specific Settings

```toml
[tool.uv.pip]
compile-bytecode = true
strict = true
generate-hashes = true
annotation-style = "line"      # line/split
extra = ["dev", "test"]
output-file = "requirements.txt"
break-system-packages = false
no-strip-markers = false
universal = false
```

## Environment Variables

### Core Configuration

```bash
# Directories
UV_CACHE_DIR=/custom/cache
UV_PROJECT_ENVIRONMENT=.venv
UV_WORKING_DIRECTORY=/path/to/project

# Configuration
UV_CONFIG_FILE=/path/to/uv.toml
UV_NO_CONFIG=1

# Python management
UV_PYTHON=3.11
UV_PYTHON_PREFERENCE=managed     # only-managed/managed/system/only-system
UV_PYTHON_DOWNLOADS=automatic    # automatic/manual/never
UV_PYTHON_INSTALL_DIR=~/.python
UV_MANAGED_PYTHON=1
UV_SYSTEM_PYTHON=1
```

### Network and Performance

```bash
# Downloads and builds
UV_CONCURRENT_DOWNLOADS=20
UV_CONCURRENT_BUILDS=8
UV_CONCURRENT_INSTALLS=4
UV_HTTP_TIMEOUT=30
UV_HTTP_RETRIES=3

# Network control
UV_OFFLINE=1
UV_NO_CACHE=1
```

### Index Configuration

```bash
# Primary index
UV_DEFAULT_INDEX=https://pypi.org/simple
UV_INDEX_URL=https://pypi.org/simple  # Deprecated

# Additional indexes
UV_INDEX="name1=https://index1.com name2=https://index2.com"
UV_EXTRA_INDEX_URL=https://custom.index.com  # Deprecated

# Index authentication
UV_INDEX_PRIVATE_REGISTRY_USERNAME=user
UV_INDEX_PRIVATE_REGISTRY_PASSWORD=pass
```

### Build Configuration

```bash
# Build control
UV_COMPILE_BYTECODE=1
UV_NO_BUILD_ISOLATION=1
UV_NO_BUILD=1
UV_NO_BUILD_PACKAGE="numpy scipy"
UV_NO_BINARY=1
UV_NO_BINARY_PACKAGE="numpy scipy"
UV_CONFIG_SETTINGS='{"editable_mode": "compat"}'

# Build constraints
UV_BUILD_CONSTRAINT=/path/to/constraints.txt
```

### Resolution Control

```bash
# Resolution strategy
UV_RESOLUTION=highest          # highest/lowest/lowest-direct
UV_PRERELEASE=if-necessary     # allow/disallow/if-necessary/if-necessary-or-explicit
UV_EXCLUDE_NEWER=2025-01-01T00:00:00Z

# Lock and sync
UV_FROZEN=1
UV_LOCKED=1
UV_NO_SYNC=1

# Dependencies
UV_DEV=1
UV_NO_DEV=1
UV_NO_EDITABLE=1
```

### Security

```bash
# Authentication
UV_KEYRING_PROVIDER=subprocess  # subprocess/disabled
UV_NATIVE_TLS=1

# Insecure hosts
UV_INSECURE_HOST="host1.com host2.com"

# Publishing
UV_PUBLISH_USERNAME=__token__
UV_PUBLISH_PASSWORD=$PYPI_TOKEN
UV_PUBLISH_TOKEN=$PYPI_TOKEN
UV_TRUSTED_PUBLISHING=automatic
```

### Output Control

```bash
# Output format
UV_NO_PROGRESS=1
UV_NO_WRAP=1
UV_QUIET=1
UV_VERBOSE=1
UV_COLOR=always  # always/never/auto
UV_LOG_CONTEXT=1
```

### Tool Management

```bash
UV_TOOL_DIR=~/.local/share/uv/tools
UV_TOOL_BIN_DIR=~/.local/bin
```

### Preview Features

```bash
UV_PREVIEW=1
UV_PREVIEW_FEATURES=feature1,feature2
```

### Advanced Settings

```bash
# Installation
UV_LINK_MODE=copy           # clone/copy/hardlink/symlink
UV_REINSTALL=1
UV_UPGRADE=1
UV_NO_INDEX=1
UV_ISOLATED=1

# Environment files
UV_ENV_FILE=.env.production
UV_NO_ENV_FILE=1

# S3 support (preview)
UV_S3_ENDPOINT_URL=https://s3.amazonaws.com

# Mirrors
UV_PYTHON_INSTALL_MIRROR=https://mirror.example.com
UV_PYPY_INSTALL_MIRROR=https://pypy-mirror.example.com

# Debug
RUST_LOG=uv=debug
RUST_BACKTRACE=1
```

## Complete Example Configuration

```toml
[project]
name = "myproject"
version = "1.0.0"
requires-python = ">=3.11"
dependencies = ["fastapi>=0.115", "torch"]

# Preferred: Use PEP 735 dependency groups
[dependency-groups]
dev = [
    "pytest>=8.4.2",
    "ruff>=0.13.3",
    "mypy>=1.18.2",
]
test = ["pytest-cov", "pytest-asyncio"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
# Project configuration
managed = true
package = true
default-groups = ["dev"]

# Resolution
resolution = "highest"
fork-strategy = "requires-python"
index-strategy = "first-index"

# Environment restrictions
environments = ["sys_platform == 'linux'"]
required-environments = ["sys_platform == 'linux' and platform_machine == 'x86_64'"]

# Constraints
constraint-dependencies = ["grpcio<1.65"]
override-dependencies = ["werkzeug==2.3.0"]
build-constraint-dependencies = ["setuptools==60.0.0"]

# Build configuration
compile-bytecode = true
no-build-isolation-package = ["flash-attn"]
config-settings = { editable_mode = "compat" }

# Cache configuration
cache-dir = "./.uv_cache"
cache-keys = [
    { file = "pyproject.toml" },
    { git = { commit = true } },
]

# Network
concurrent-downloads = 20
concurrent-builds = 8

# Python management
python-preference = "managed"
python-downloads = "automatic"

# Security
keyring-provider = "subprocess"

# Preview features
preview = true

# Extra build configuration
[tool.uv.extra-build-dependencies]
flash-attn = [{ requirement = "torch", match-runtime = true }]

[tool.uv.extra-build-variables]
flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }

# Package sources
[tool.uv.sources]
torch = { index = "pytorch-cu121" }
internal-lib = { workspace = true }

# Custom indexes
[[tool.uv.index]]
name = "pytorch-cu121"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[[tool.uv.index]]
name = "private"
url = "https://packages.example.com/simple"
authenticate = "always"

# Workspace configuration
[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/deprecated"]

# pip-specific settings
[tool.uv.pip]
compile-bytecode = true
strict = true
generate-hashes = false

# Conflict resolution
[[tool.uv.conflicts]]
extra = ["cuda", "rocm"]
```

## Configuration Best Practices

1. **Project vs User Config**: Keep project-specific settings in `pyproject.toml`, user preferences in `~/.config/uv/uv.toml`
2. **Security**: Never commit credentials to version control, use environment variables
3. **Index Pinning**: Use `explicit = true` for custom indexes to prevent accidents
4. **Build Isolation**: Only disable for problematic packages, document why
5. **Cache**: Use project-local cache (`.uv_cache`) for CI reproducibility
6. **Python Preference**: Use `managed` for consistent team environments
7. **Lockfiles**: Always commit `uv.lock` for reproducible installs
8. **Environment Restrictions**: Use `environments` to prevent platform-specific resolution issues
9. **Preview Features**: Test in development before enabling in production

## uv.toml Format

`uv.toml` uses same structure as `pyproject.toml` but **without** `[tool.uv]` prefix:

```toml
# uv.toml (no [tool.uv] prefix)
managed = true
resolution = "highest"
compile-bytecode = true

[[index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
```

Equivalent to:

```toml
# pyproject.toml (with [tool.uv] prefix)
[tool.uv]
managed = true
resolution = "highest"
compile-bytecode = true

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
```