uv Cheatsheet — Configuration & Cache

·Updated March 20th, 2026
pythonuvconfigurationcacheenvironment-variables

Configuration Hierarchy

uv reads configuration from (highest to lowest priority):

  1. CLI flags — e.g., --index-url
  2. Environment variables — e.g., UV_INDEX_URL
  3. Project-level — uv.toml or pyproject.toml [tool.uv] in the project directory (or nearest parent)
  4. User-level — ~/.config/uv/uv.toml
  5. System-level — /etc/uv/uv.toml

If both uv.toml and pyproject.toml exist in the same directory, uv.toml wins and the [tool.uv] section in pyproject.toml is ignored.

pyproject.toml Configuration

All uv-specific settings go under [tool.uv]:

toml
[tool.uv]
# Use a custom index
index-url = "https://my-private-registry.com/simple"

# Extra indexes
extra-index-url = ["https://pypi.org/simple"]

# Always exclude certain transitive deps
exclude-dependencies = ["werkzeug"]

# Force version constraints on transitive deps
constraint-dependencies = ["grpcio<1.65"]

# Override dep versions regardless of what's requested
override-dependencies = ["numpy==1.26.4"]

# Dependency groups to install by default
default-groups = ["dev"]

# Disable build isolation for specific packages
no-build-isolation-package = ["cchardet"]

# Default version specifier style when running uv add
default-version-specifier = ">="

Standalone uv.toml

Same structure, but without the [tool.uv] prefix:

toml
# ~/.config/uv/uv.toml  (user-level)
index-url = "https://my-company-registry.com/simple"

Custom Package Indexes

toml
# pyproject.toml
[tool.uv]
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"

[[tool.uv.index]]
name = "company"
url = "https://registry.company.com/simple"

[tool.uv.sources]
torch = { index = "pytorch" }

Key Environment Variables

VariablePurpose
UV_INDEX_URLDefault package index
UV_EXTRA_INDEX_URLAdditional indexes (space-separated)
UV_CACHE_DIROverride cache directory
UV_PYTHON_INSTALL_DIROverride managed Python install dir
UV_PYTHON_DOWNLOADSauto (default), never, manual
UV_NO_MODIFY_PATH1 to prevent installer from touching shell profiles
UV_LINK_MODEclone, copy, hardlink, or symlink
UV_PROJECT_ENVIRONMENTOverride the venv path (default: .venv)
UV_NO_SYNC1 to skip auto-sync in uv run
UV_FROZEN1 to never update the lockfile
UV_COMPILE_BYTECODE1 to compile .pyc files during install
VIRTUAL_ENVRespected by uv pip commands
UV_HTTP_TIMEOUTHTTP timeout in seconds (default: 30)

Cache Management

uv uses a global cache at ~/.cache/uv (Linux) for deduplicating packages across projects.

bash
# Show cache directory
uv cache dir

# Clear the entire cache
uv cache clean

# Clear cache for a specific package
uv cache clean requests

# Prune unreferenced cache entries
uv cache prune

# Override cache location
export UV_CACHE_DIR=/tmp/uv-cache

Storage Directories (Linux defaults)

WhatPath
Cache~/.cache/uv/
Managed Python~/.local/share/uv/python/
Tools~/.local/share/uv/tools/
Tool binaries~/.local/bin/
User config~/.config/uv/uv.toml
System config/etc/uv/uv.toml

These follow XDG conventions. Override with UV_CACHE_DIR, UV_PYTHON_INSTALL_DIR, etc.

Disable Configuration Discovery

bash
# Ignore all config files
uv run --no-config main.py

# Use a specific config file
uv run --config-file /path/to/uv.toml main.py