> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

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

<ParamField path="UV_CACHE_DIR" type="string">
  Path to the cache directory. Overrides the default platform-specific cache location.
</ParamField>

```bash theme={null}
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.

<ParamField path="UV_CONFIG_FILE" type="string">
  Path to a `uv.toml` file. When set, uv ignores all discovered configuration files.
</ParamField>

```bash theme={null}
export UV_CONFIG_FILE="/path/to/custom-uv.toml"
uv sync
```

### UV\_NO\_CONFIG

Disable all persistent configuration file discovery.

<ParamField path="UV_NO_CONFIG" type="boolean">
  Set to `1` or `true` to disable configuration file discovery.
</ParamField>

```bash theme={null}
export UV_NO_CONFIG=1
uv sync
```

## Index Configuration

### UV\_INDEX

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

<ParamField path="UV_INDEX" type="string">
  Index URL, optionally with a name prefix: `name=url` or just `url`.
</ParamField>

```bash theme={null}
# 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.

<ParamField path="UV_DEFAULT_INDEX" type="string">
  Default index URL, optionally with a name prefix: `name=url` or just `url`.
</ParamField>

```bash theme={null}
export UV_DEFAULT_INDEX="https://pypi.private.example.com/simple"
uv sync
```

### UV\_INDEX\_STRATEGY

Control how uv searches across multiple indexes.

<ParamField path="UV_INDEX_STRATEGY" type="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
</ParamField>

```bash theme={null}
export UV_INDEX_STRATEGY="unsafe-best-match"
uv sync
```

### UV\_INDEX\_\*\_USERNAME

Provide username for a named index.

<ParamField path="UV_INDEX_<NAME>_USERNAME" type="string">
  Username for authentication. `<NAME>` is the uppercase index name with non-alphanumeric characters replaced by underscores.
</ParamField>

```bash theme={null}
# For an index named "internal-proxy"
export UV_INDEX_INTERNAL_PROXY_USERNAME="myuser"
```

### UV\_INDEX\_\*\_PASSWORD

Provide password or token for a named index.

<ParamField path="UV_INDEX_<NAME>_PASSWORD" type="string">
  Password or token for authentication. `<NAME>` follows the same normalization as USERNAME.
</ParamField>

```bash theme={null}
# 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.

<ParamField path="UV_KEYRING_PROVIDER" type="string" default="disabled">
  Keyring provider:

  * `disabled`: No keyring
  * `subprocess`: Invoke `keyring` CLI
</ParamField>

```bash theme={null}
export UV_KEYRING_PROVIDER=subprocess
uv sync
```

### NETRC

Specify a custom netrc file location.

<ParamField path="NETRC" type="string">
  Path to netrc file containing credentials. Defaults to `~/.netrc` if not set.
</ParamField>

```bash theme={null}
export NETRC="/secure/credentials/netrc"
uv sync
```

### UV\_NO\_HF\_TOKEN

Disable automatic Hugging Face authentication.

<ParamField path="UV_NO_HF_TOKEN" type="boolean">
  Set to `1` to disable Hugging Face token usage.
</ParamField>

```bash theme={null}
export UV_NO_HF_TOKEN=1
uv sync
```

## Project Configuration

### UV\_PROJECT\_ENVIRONMENT

Customize the project virtual environment path.

<ParamField path="UV_PROJECT_ENVIRONMENT" type="string" default=".venv">
  Path to the project virtual environment. Relative paths are resolved from the workspace root.
</ParamField>

```bash theme={null}
# Relative path
export UV_PROJECT_ENVIRONMENT=".venv-custom"

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

uv sync
```

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

### UV\_PYTHON\_INSTALL\_DIR

Override the Python installation directory.

<ParamField path="UV_PYTHON_INSTALL_DIR" type="string">
  Directory where managed Python versions are installed.
</ParamField>

```bash theme={null}
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.

<ParamField path="UV_PYTHON_BIN_DIR" type="string">
  Directory where Python executables are installed.
</ParamField>

```bash theme={null}
export UV_PYTHON_BIN_DIR="/usr/local/bin"
uv python install 3.12
```

## Tool Configuration

### UV\_TOOL\_DIR

Customize the tools installation directory.

<ParamField path="UV_TOOL_DIR" type="string">
  Directory where tools are installed.
</ParamField>

```bash theme={null}
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.

<ParamField path="UV_TOOL_BIN_DIR" type="string">
  Directory where tool executables are installed.
</ParamField>

```bash theme={null}
export UV_TOOL_BIN_DIR="/usr/local/bin"
uv tool install ruff
```

## Environment Files

### UV\_ENV\_FILE

Load environment variables from dotenv files.

<ParamField path="UV_ENV_FILE" type="string">
  Path(s) to dotenv files. Multiple paths separated by spaces.
</ParamField>

```bash theme={null}
# 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.

<ParamField path="UV_NO_ENV_FILE" type="boolean">
  Set to `1` to disable loading environment files.
</ParamField>

```bash theme={null}
export UV_NO_ENV_FILE=1
uv run -- python script.py
```

## Installation & Upgrades

### UV\_INSTALL\_DIR

Customize where the uv executable is installed.

<ParamField path="UV_INSTALL_DIR" type="string">
  Directory where `uv` and `uvx` executables are installed when using the standalone installer.
</ParamField>

```bash theme={null}
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.

<ParamField path="UV_NO_MODIFY_PATH" type="boolean">
  Set to `1` to prevent PATH modifications during installation.
</ParamField>

```bash theme={null}
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.

<ParamField path="UV_PUBLISH_URL" type="string">
  URL for publishing packages.
</ParamField>

```bash theme={null}
export UV_PUBLISH_URL="https://upload.pypi.org/legacy/"
uv publish
```

### UV\_PUBLISH\_USERNAME

Provide username for publishing.

<ParamField path="UV_PUBLISH_USERNAME" type="string">
  Username for package publishing authentication.
</ParamField>

```bash theme={null}
export UV_PUBLISH_USERNAME="__token__"
export UV_PUBLISH_PASSWORD="pypi-xxxxxxxxxxxx"
uv publish
```

### UV\_PUBLISH\_PASSWORD

Provide password or token for publishing.

<ParamField path="UV_PUBLISH_PASSWORD" type="string">
  Password or token for package publishing authentication.
</ParamField>

```bash theme={null}
export UV_PUBLISH_PASSWORD="pypi-xxxxxxxxxxxx"
uv publish
```

## Preview Features

### UV\_PREVIEW

Enable all preview features.

<ParamField path="UV_PREVIEW" type="boolean">
  Set to `1` to enable all preview features.
</ParamField>

```bash theme={null}
export UV_PREVIEW=1
uv run
```

### UV\_PREVIEW\_FEATURES

Enable specific preview features.

<ParamField path="UV_PREVIEW_FEATURES" type="string">
  Comma-separated list of preview features to enable.
</ParamField>

```bash theme={null}
# 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.

<ParamField path="UV_GIT_LFS" type="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
</ParamField>

```bash theme={null}
export UV_GIT_LFS=enabled
uv sync
```

## Cache Management

### UV\_LOCK\_TIMEOUT

Set timeout for cache lock operations.

<ParamField path="UV_LOCK_TIMEOUT" type="integer" default="300">
  Timeout in seconds for acquiring cache locks. Used by `uv cache clean` and similar operations.
</ParamField>

```bash theme={null}
# 10 minute timeout
export UV_LOCK_TIMEOUT=600
uv cache clean
```

## TLS Configuration

### UV\_NATIVE\_TLS

Use native TLS implementation instead of rustls.

<ParamField path="UV_NATIVE_TLS" type="boolean">
  Set to `true` to use system-native TLS.
</ParamField>

```bash theme={null}
export UV_NATIVE_TLS=true
uv sync
```

## Examples

### CI/CD Environment

```bash theme={null}
# 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

```dockerfile theme={null}
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

```bash theme={null}
# .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

```bash theme={null}
# 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

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
# 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](/configuration/files) - Persistent configuration with pyproject.toml and uv.toml
* [Authentication](/configuration/authentication) - Configure credentials for private indexes
* [Indexes](/configuration/indexes) - Custom package index configuration
* [Settings Reference](/reference/settings) - Complete settings documentation