Environment Variables

Environment variables provide a way to configure uv’s behavior without modifying configuration files. They take precedence over persistent configuration but are overridden by command-line arguments.

General Configuration

UV_CACHE_DIR

Specify the cache directory location.

UV_CACHE_DIR

string

Path to the cache directory. Overrides the default platform-specific cache location.

export UV_CACHE_DIR="/var/cache/uv"
uv sync

Default locations:

Unix: $XDG_CACHE_HOME/uv or $HOME/.cache/uv
Windows: %LOCALAPPDATA%\uv\cache

UV_CONFIG_FILE

Use a specific configuration file instead of discovering one.

UV_CONFIG_FILE

string

Path to a uv.toml file. When set, uv ignores all discovered configuration files.

export UV_CONFIG_FILE="/path/to/custom-uv.toml"
uv sync

UV_NO_CONFIG

Disable all persistent configuration file discovery.

UV_NO_CONFIG

boolean

Set to 1 or true to disable configuration file discovery.

export UV_NO_CONFIG=1
uv sync

Index Configuration

UV_INDEX

Add an additional package index (equivalent to --index).

UV_INDEX

string

Index URL, optionally with a name prefix: name=url or just url.

# With name
export UV_INDEX="pytorch=https://download.pytorch.org/whl/cpu"

# Without name
export UV_INDEX="https://download.pytorch.org/whl/cpu"

uv sync

UV_DEFAULT_INDEX

Set the default package index, replacing PyPI.

UV_DEFAULT_INDEX

string

Default index URL, optionally with a name prefix: name=url or just url.

export UV_DEFAULT_INDEX="https://pypi.private.example.com/simple"
uv sync

UV_INDEX_STRATEGY

Control how uv searches across multiple indexes.

UV_INDEX_STRATEGY

string

default:"first-index"

Index search strategy:

first-index: Use first index containing the package (prevents dependency confusion)
unsafe-first-match: Prefer first index with compatible version
unsafe-best-match: Select best version across all indexes

export UV_INDEX_STRATEGY="unsafe-best-match"
uv sync

UV_INDEX_*_USERNAME

Provide username for a named index.

UV_INDEX_<NAME>_USERNAME

string

Username for authentication. <NAME> is the uppercase index name with non-alphanumeric characters replaced by underscores.

# For an index named "internal-proxy"
export UV_INDEX_INTERNAL_PROXY_USERNAME="myuser"

UV_INDEX_*_PASSWORD

Provide password or token for a named index.

UV_INDEX_<NAME>_PASSWORD

string

Password or token for authentication. <NAME> follows the same normalization as USERNAME.

# For an index named "internal-proxy"
export UV_INDEX_INTERNAL_PROXY_PASSWORD="mytoken"
uv sync

Examples:

Index Name	Username Variable	Password Variable
`internal-proxy`	`UV_INDEX_INTERNAL_PROXY_USERNAME`	`UV_INDEX_INTERNAL_PROXY_PASSWORD`
`azure.artifacts`	`UV_INDEX_AZURE_ARTIFACTS_USERNAME`	`UV_INDEX_AZURE_ARTIFACTS_PASSWORD`
`my_registry`	`UV_INDEX_MY_REGISTRY_USERNAME`	`UV_INDEX_MY_REGISTRY_PASSWORD`

Authentication

UV_KEYRING_PROVIDER

Enable keyring provider for credential retrieval.

UV_KEYRING_PROVIDER

string

default:"disabled"

Keyring provider:

disabled: No keyring
subprocess: Invoke keyring CLI

export UV_KEYRING_PROVIDER=subprocess
uv sync

NETRC

Specify a custom netrc file location.

NETRC

string

Path to netrc file containing credentials. Defaults to ~/.netrc if not set.

export NETRC="/secure/credentials/netrc"
uv sync

UV_NO_HF_TOKEN

Disable automatic Hugging Face authentication.

UV_NO_HF_TOKEN

boolean

Set to 1 to disable Hugging Face token usage.

export UV_NO_HF_TOKEN=1
uv sync

Project Configuration

UV_PROJECT_ENVIRONMENT

Customize the project virtual environment path.

UV_PROJECT_ENVIRONMENT

string

default:".venv"

Path to the project virtual environment. Relative paths are resolved from the workspace root.

# Relative path
export UV_PROJECT_ENVIRONMENT=".venv-custom"

# Absolute path
export UV_PROJECT_ENVIRONMENT="/opt/venvs/myproject"

uv sync

When using an absolute path across multiple projects, the environment will be overwritten. This is primarily intended for CI/Docker environments.

UV_PYTHON_INSTALL_DIR

Override the Python installation directory.

UV_PYTHON_INSTALL_DIR

string

Directory where managed Python versions are installed.

export UV_PYTHON_INSTALL_DIR="/opt/python"
uv python install 3.12

Default: ~/.local/share/uv/python (Unix) or %LOCALAPPDATA%\uv\python (Windows)

UV_PYTHON_BIN_DIR

Override the Python executable directory.

UV_PYTHON_BIN_DIR

string

Directory where Python executables are installed.

export UV_PYTHON_BIN_DIR="/usr/local/bin"
uv python install 3.12

Tool Configuration

UV_TOOL_DIR

Customize the tools installation directory.

UV_TOOL_DIR

string

Directory where tools are installed.

export UV_TOOL_DIR="/opt/uv-tools"
uv tool install ruff

Default: ~/.local/share/uv/tools (Unix) or %LOCALAPPDATA%\uv\tools (Windows)

UV_TOOL_BIN_DIR

Customize the tool executable directory.

UV_TOOL_BIN_DIR

string

Directory where tool executables are installed.

export UV_TOOL_BIN_DIR="/usr/local/bin"
uv tool install ruff

Environment Files

UV_ENV_FILE

Load environment variables from dotenv files.

UV_ENV_FILE

string

Path(s) to dotenv files. Multiple paths separated by spaces.

# Single file
export UV_ENV_FILE=".env"

# Multiple files (later files override earlier ones)
export UV_ENV_FILE=".env .env.local"

uv run -- python script.py

UV_NO_ENV_FILE

Disable dotenv file loading.

UV_NO_ENV_FILE

boolean

Set to 1 to disable loading environment files.

export UV_NO_ENV_FILE=1
uv run -- python script.py

Installation & Upgrades

UV_INSTALL_DIR

Customize where the uv executable is installed.

UV_INSTALL_DIR

string

Directory where uv and uvx executables are installed when using the standalone installer.

export UV_INSTALL_DIR="/usr/local/bin"
curl -LsSf https://astral.sh/uv/install.sh | sh

UV_NO_MODIFY_PATH

Prevent the installer from modifying PATH.

UV_NO_MODIFY_PATH

boolean

Set to 1 to prevent PATH modifications during installation.

export UV_NO_MODIFY_PATH=1
curl -LsSf https://astral.sh/uv/install.sh | sh

Publishing

UV_PUBLISH_URL

Set the publish URL without modifying project configuration.

UV_PUBLISH_URL

string

URL for publishing packages.

export UV_PUBLISH_URL="https://upload.pypi.org/legacy/"
uv publish

UV_PUBLISH_USERNAME

Provide username for publishing.

UV_PUBLISH_USERNAME

string

Username for package publishing authentication.

export UV_PUBLISH_USERNAME="__token__"
export UV_PUBLISH_PASSWORD="pypi-xxxxxxxxxxxx"
uv publish

UV_PUBLISH_PASSWORD

Provide password or token for publishing.

UV_PUBLISH_PASSWORD

string

Password or token for package publishing authentication.

export UV_PUBLISH_PASSWORD="pypi-xxxxxxxxxxxx"
uv publish

Preview Features

UV_PREVIEW

Enable all preview features.

UV_PREVIEW

boolean

Set to 1 to enable all preview features.

export UV_PREVIEW=1
uv run

UV_PREVIEW_FEATURES

Enable specific preview features.

UV_PREVIEW_FEATURES

string

Comma-separated list of preview features to enable.

# Enable native authentication storage
export UV_PREVIEW_FEATURES=native-auth
uv sync

# Enable multiple features
export UV_PREVIEW_FEATURES=native-auth,feature2
uv sync

Available preview features:

native-auth: Use system-native credential storage (Keychain/Credential Manager/Secret Service)

Git Configuration

UV_GIT_LFS

Control Git LFS behavior for dependencies.

UV_GIT_LFS

string

Configure Git LFS for all Git sources without explicit LFS setting:

auto: Use LFS if available (default)
enabled: Require LFS
disabled: Never use LFS

export UV_GIT_LFS=enabled
uv sync

Cache Management

UV_LOCK_TIMEOUT

Set timeout for cache lock operations.

UV_LOCK_TIMEOUT

integer

default:"300"

Timeout in seconds for acquiring cache locks. Used by uv cache clean and similar operations.

# 10 minute timeout
export UV_LOCK_TIMEOUT=600
uv cache clean

TLS Configuration

UV_NATIVE_TLS

Use native TLS implementation instead of rustls.

UV_NATIVE_TLS

boolean

Set to true to use system-native TLS.

export UV_NATIVE_TLS=true
uv sync

Examples

CI/CD Environment

# Use shared cache
export UV_CACHE_DIR="/ci-cache/uv"

# Disable config files
export UV_NO_CONFIG=1

# Use private registry
export UV_DEFAULT_INDEX="https://pypi.company.com/simple"
export UV_INDEX_PYPI_COMPANY_COM_USERNAME="ci-bot"
export UV_INDEX_PYPI_COMPANY_COM_PASSWORD="$CI_TOKEN"

# Install in specific location
export UV_PROJECT_ENVIRONMENT="/opt/app/.venv"

uv sync

Docker Build

FROM python:3.12

# Configure uv cache in build context
ENV UV_CACHE_DIR=/root/.cache/uv
ENV UV_NO_CACHE=1

# Install uv
RUN pip install uv

# Copy and install dependencies
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-editable

# Copy application
COPY . .

CMD ["uv", "run", "python", "app.py"]

Local Development with Multiple Indexes

# .envrc (for direnv)
export UV_INDEX="pytorch=https://download.pytorch.org/whl/cpu"
export UV_INDEX_STRATEGY="first-index"
export UV_KEYRING_PROVIDER=subprocess
export UV_ENV_FILE=".env.local"

Airgapped/Offline Environment

# Point to local mirror
export UV_DEFAULT_INDEX="file:///mnt/pypi-mirror/simple"

# Disable external network access
export UV_NO_CACHE=1

uv sync

Azure DevOps Pipeline

steps:
  - script: |
      export UV_INDEX_AZURE_ARTIFACTS_USERNAME=dummy
      export UV_INDEX_AZURE_ARTIFACTS_PASSWORD="$(System.AccessToken)"
      export UV_CACHE_DIR="$(Pipeline.Workspace)/.uv-cache"
      uv sync
    displayName: 'Install dependencies'

GitHub Actions

steps:
  - name: Install dependencies
    env:
      UV_CACHE_DIR: ${{ runner.temp }}/.uv-cache
      UV_INDEX_PRIVATE_USERNAME: ${{ secrets.PYPI_USERNAME }}
      UV_INDEX_PRIVATE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
    run: uv sync

Precedence Order

Configuration sources in order of precedence (highest to lowest):

Command-line arguments (e.g., --cache-dir /tmp/cache)
Environment variables (e.g., UV_CACHE_DIR=/tmp/cache)
Project configuration (e.g., pyproject.toml or uv.toml)
User configuration (e.g., ~/.config/uv/uv.toml)
System configuration (e.g., /etc/uv/uv.toml)
Defaults

Example:

# User config sets cache-dir to ~/.cache/uv
# Project config sets cache-dir to ./.cache
# Environment variable overrides both
export UV_CACHE_DIR="/tmp/cache"

# Command-line argument has final say
uv sync --cache-dir /var/cache/uv
# Uses: /var/cache/uv

Configuration Files - Persistent configuration with pyproject.toml and uv.toml
Authentication - Configure credentials for private indexes
Indexes - Custom package index configuration
Settings Reference - Complete settings documentation

Get Started

Core Concepts

Guides

Integrations

Configuration

​General Configuration

​UV_CACHE_DIR

​UV_CONFIG_FILE

​UV_NO_CONFIG

​Index Configuration

​UV_INDEX

​UV_DEFAULT_INDEX

​UV_INDEX_STRATEGY

​UV_INDEX_*_USERNAME

​UV_INDEX_*_PASSWORD

​Authentication

​UV_KEYRING_PROVIDER

​NETRC

​UV_NO_HF_TOKEN

​Project Configuration

​UV_PROJECT_ENVIRONMENT

​UV_PYTHON_INSTALL_DIR

​UV_PYTHON_BIN_DIR

​Tool Configuration

​UV_TOOL_DIR

​UV_TOOL_BIN_DIR

​Environment Files

​UV_ENV_FILE

​UV_NO_ENV_FILE

​Installation & Upgrades

​UV_INSTALL_DIR

​UV_NO_MODIFY_PATH

​Publishing

​UV_PUBLISH_URL

​UV_PUBLISH_USERNAME

​UV_PUBLISH_PASSWORD

​Preview Features

​UV_PREVIEW

​UV_PREVIEW_FEATURES

​Git Configuration

​UV_GIT_LFS

​Cache Management

​UV_LOCK_TIMEOUT

​TLS Configuration

​UV_NATIVE_TLS

​Examples

​CI/CD Environment

​Docker Build

​Local Development with Multiple Indexes

​Airgapped/Offline Environment

​Azure DevOps Pipeline

​GitHub Actions

​Precedence Order

​Related Resources

Build docs developers (and LLMs) love

General Configuration

UV_CACHE_DIR

UV_CONFIG_FILE

UV_NO_CONFIG

Index Configuration

UV_INDEX

UV_DEFAULT_INDEX

UV_INDEX_STRATEGY

UV_INDEX_*_USERNAME

UV_INDEX_*_PASSWORD

Authentication

UV_KEYRING_PROVIDER

NETRC

UV_NO_HF_TOKEN

Project Configuration

UV_PROJECT_ENVIRONMENT

UV_PYTHON_INSTALL_DIR

UV_PYTHON_BIN_DIR

Tool Configuration

UV_TOOL_DIR

UV_TOOL_BIN_DIR

Environment Files

UV_ENV_FILE

UV_NO_ENV_FILE

Installation & Upgrades

UV_INSTALL_DIR

UV_NO_MODIFY_PATH

Publishing

UV_PUBLISH_URL

UV_PUBLISH_USERNAME

UV_PUBLISH_PASSWORD

Preview Features

UV_PREVIEW

UV_PREVIEW_FEATURES

Git Configuration

UV_GIT_LFS

Cache Management

UV_LOCK_TIMEOUT

TLS Configuration

UV_NATIVE_TLS

Examples

CI/CD Environment

Docker Build

Local Development with Multiple Indexes

Airgapped/Offline Environment

Azure DevOps Pipeline

GitHub Actions

Precedence Order

Related Resources