Skip to main content
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:
pyproject.toml
[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:
uv.toml
index-url = "https://pypi.org/simple"

[[index]]
url = "https://test.pypi.org/simple"
default = true
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.

​
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: 
~/.config/uv/uv.toml
User- and system-level configuration files cannot use the pyproject.toml format. Only uv.toml is supported.

​
System-Level Configuration

System-level configuration files are located at: 
/etc/uv/uv.toml

​
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:
user-level uv.toml
index-url = "https://pypi.org/simple"

[[index]]
url = "https://internal.example.com/simple"
project-level uv.toml
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: 
uv sync --no-config

​
Using a Custom Configuration File

To use a specific configuration file: 
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

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

​
Configuring the pip Interface

A dedicated [tool.uv.pip] section is available for configuring only the uv pip command-line interface:
pyproject.toml
[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: 
# 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: 
# 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: 
# Via flag
uv run --no-env-file -- python script.py

# Via environment variable
export UV_NO_ENV_FILE=1
uv run -- python script.py
If the same variable is defined in both the environment and a .env file, the environment value takes precedence.

​
Example Configurations

​
Basic Project Configuration

pyproject.toml
[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

~/.config/uv/uv.toml
# 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

uv.toml
# 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"

Build docs developers (and LLMs) love

Get started for freeTalk to us