Environment Variables

Complete reference for all UV_* environment variables that control uv’s behavior

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

1. Command-line arguments (e.g., --cache-dir /tmp/cache)
2. Environment variables (e.g., UV_CACHE_DIR=/tmp/cache)
3. Project configuration (e.g., pyproject.toml or uv.toml)
4. User configuration (e.g., ~/.config/uv/uv.toml)
5. System configuration (e.g., /etc/uv/uv.toml)
6. 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

Related Resources

• 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