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

# Configuration Files

> Learn how to configure uv using pyproject.toml and uv.toml files

uv supports persistent configuration files at both the project and user levels to customize its behavior.

## Configuration File Types

### pyproject.toml

For project-level configuration, uv reads settings from the `[tool.uv]` table in `pyproject.toml`:

```toml pyproject.toml theme={null}
[tool.uv]
index-url = "https://pypi.org/simple"

[[tool.uv.index]]
url = "https://test.pypi.org/simple"
default = true
```

If there is no `[tool.uv]` table, the `pyproject.toml` file will be ignored.

### uv.toml

uv also searches for `uv.toml` files, which follow an identical structure but omit the `[tool.uv]` prefix:

```toml uv.toml theme={null}
index-url = "https://pypi.org/simple"

[[index]]
url = "https://test.pypi.org/simple"
default = true
```

<Note>
  `uv.toml` files take precedence over `pyproject.toml` files. If both files are present in a directory, configuration will be read from `uv.toml`, and the `[tool.uv]` section in `pyproject.toml` will be ignored.
</Note>

## Configuration Hierarchy

uv searches for configuration files in the following order:

### Project-Level Configuration

uv searches for `pyproject.toml` or `uv.toml` in:

1. The current directory
2. The nearest parent directory

In workspaces, uv begins its search at the workspace root, ignoring any configuration defined in workspace members. Since the workspace is locked as a single unit, configuration is shared across all members.

### User-Level Configuration

User-level configuration files are stored in system-specific directories:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  ~/.config/uv/uv.toml
  ```

  ```bash Windows theme={null}
  %APPDATA%\uv\uv.toml
  ```
</CodeGroup>

<Warning>
  User- and system-level configuration files cannot use the `pyproject.toml` format. Only `uv.toml` is supported.
</Warning>

### System-Level Configuration

System-level configuration files are located at:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  /etc/uv/uv.toml
  ```

  ```bash Windows theme={null}
  %PROGRAMDATA%\uv\uv.toml
  ```
</CodeGroup>

## Configuration Precedence

Settings are merged across configuration levels with the following precedence (highest to lowest):

1. **Command-line arguments** - Highest priority
2. **Environment variables** - Override persistent configuration
3. **Project-level configuration** - Local `pyproject.toml` or `uv.toml`
4. **User-level configuration** - `~/.config/uv/uv.toml`
5. **System-level configuration** - `/etc/uv/uv.toml` - Lowest priority

### Merge Behavior

* **Scalar values** (strings, numbers, booleans): Project-level values override user-level values
* **Arrays**: Arrays are concatenated, with project-level settings appearing first

Example:

```toml user-level uv.toml theme={null}
index-url = "https://pypi.org/simple"

[[index]]
url = "https://internal.example.com/simple"
```

```toml project-level uv.toml theme={null}
index-url = "https://custom.pypi.org/simple"  # Overrides user-level

[[index]]
url = "https://pytorch.org/whl/cpu"  # Prepended to user-level indexes
```

## Configuration File Options

### Disabling Configuration Discovery

To disable all persistent configuration:

```bash theme={null}
uv sync --no-config
```

### Using a Custom Configuration File

To use a specific configuration file:

```bash theme={null}
uv sync --config-file /path/to/uv.toml
```

When provided, this file replaces all discovered configuration files, including user-level configuration.

## Tool Commands and Configuration

<Info>
  For `uv tool` commands, which operate at the user level, local configuration files are ignored. uv will exclusively read from user-level configuration (e.g., `~/.config/uv/uv.toml`) and system-level configuration (e.g., `/etc/uv/uv.toml`).
</Info>

## Configuring the pip Interface

A dedicated `[tool.uv.pip]` section is available for configuring only the `uv pip` command-line interface:

```toml pyproject.toml theme={null}
[tool.uv.pip]
index-url = "https://test.pypi.org/simple"
```

Settings in this section:

* Only apply to `uv pip` commands (e.g., `uv pip install`, `uv pip sync`)
* Do NOT apply to other uv commands (`uv sync`, `uv lock`, `uv run`)
* Override corresponding top-level settings when using `uv pip`

## Environment Variable Files

`uv run` can load environment variables from dotenv files (e.g., `.env`, `.env.local`, `.env.development`).

### Loading Environment Files

To load a `.env` file:

```bash theme={null}
# Via command line
uv run --env-file .env -- python script.py

# Via environment variable
export UV_ENV_FILE=".env"
uv run -- python script.py
```

### Multiple Environment Files

Provide multiple files with subsequent files overriding previous values:

```bash theme={null}
# Command line
uv run --env-file .env --env-file .env.local -- python script.py

# Environment variable (space-separated)
export UV_ENV_FILE=".env .env.local"
uv run -- python script.py
```

### Disabling Environment Files

To disable dotenv loading:

```bash theme={null}
# Via flag
uv run --no-env-file -- python script.py

# Via environment variable
export UV_NO_ENV_FILE=1
uv run -- python script.py
```

<Note>
  If the same variable is defined in both the environment and a `.env` file, the environment value takes precedence.
</Note>

## Example Configurations

### Basic Project Configuration

```toml pyproject.toml theme={null}
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"

[tool.uv]
index-url = "https://pypi.org/simple"
cache-dir = "./.uv-cache"

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
```

### User-Level Configuration

```toml ~/.config/uv/uv.toml theme={null}
# Default index for all projects
index-url = "https://pypi.org/simple"

# Always use keyring for authentication
keyring-provider = "subprocess"

# Custom cache directory
cache-dir = "/var/cache/uv"
```

### Workspace Configuration

```toml uv.toml theme={null}
# Configuration at workspace root applies to all members
no-build-isolation-package = ["flash-attn"]

[[index]]
name = "internal"
url = "https://internal.example.com/simple"
authenticate = "always"
```

## Related Resources

* [Settings Reference](/reference/settings) - Complete list of available settings
* [Indexes](/configuration/indexes) - Configure custom package indexes
* [Environment Variables](/configuration/environment-variables) - Environment variable reference