gh-jamie-bitflight-claude-skills-development-skills/skills/uv/references/configuration.md

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

[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

[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

[[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

[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

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

Build Configuration

[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

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

pip-Specific Settings

[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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

Preview Features

UV_PREVIEW=1
UV_PREVIEW_FEATURES=feature1,feature2

Advanced Settings

# 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

[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:

# 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:

# 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"