Environment variables

uv defines and respects the following environment variables:

`UV_BREAK_SYSTEM_PACKAGES`

added in 0.1.32

Equivalent to the --break-system-packages command-line argument. If set to true, uv will allow the installation of packages that conflict with system-installed packages.

WARNING: UV_BREAK_SYSTEM_PACKAGES=true is intended for use in continuous integration (CI) or containerized environments and should be used with caution, as modifying the system Python can lead to unexpected behavior.

`UV_BUILD_CONSTRAINT`

added in 0.2.34

Equivalent to the --build-constraints command-line argument. If set, uv will use this file as constraints for any source distribution builds. Uses space-separated list of files.

`UV_CACHE_DIR`

added in 0.0.5

Equivalent to the --cache-dir command-line argument. If set, uv will use this directory for caching instead of the default cache directory.

`UV_COMPILE_BYTECODE`

added in 0.3.3

Equivalent to the --compile-bytecode command-line argument. If set, uv will compile Python source files to bytecode after installation.

`UV_COMPILE_BYTECODE_TIMEOUT`

added in 0.7.22

Timeout (in seconds) for bytecode compilation.

`UV_CONCURRENT_BUILDS`

added in 0.1.43

Sets the maximum number of source distributions that uv will build concurrently at any given time.

`UV_CONCURRENT_DOWNLOADS`

added in 0.1.43

Sets the maximum number of in-flight concurrent downloads that uv will perform at any given time.

`UV_CONCURRENT_INSTALLS`

added in 0.1.45

Controls the number of threads used when installing and unzipping packages.

`UV_CONFIG_FILE`

added in 0.1.34

Equivalent to the --config-file command-line argument. Expects a path to a local uv.toml file to use as the configuration file.

`UV_CONSTRAINT`

added in 0.1.36

Equivalent to the --constraints command-line argument. If set, uv will use this file as the constraints file. Uses space-separated list of files.

`UV_CREDENTIALS_DIR`

added in 0.8.15

The directory for storage of credentials when using a plain text backend.

`UV_CUSTOM_COMPILE_COMMAND`

added in 0.1.23

Equivalent to the --custom-compile-command command-line argument.

Used to override uv in the output header of the requirements.txt files generated by uv pip compile. Intended for use-cases in which uv pip compile is called from within a wrapper script, to include the name of the wrapper script in the output file.

`UV_DEFAULT_INDEX`

added in 0.4.23

Equivalent to the --default-index command-line argument. If set, uv will use this URL as the default index when searching for packages.

`UV_DEV`

added in 0.8.7

Equivalent to the --dev command-line argument. If set, uv will include development dependencies.

`UV_DOWNLOAD_URL`

added in 0.8.4

The URL from which to download uv using the standalone installer. By default, installs from uv's GitHub Releases. INSTALLER_DOWNLOAD_URL is also supported as an alias, for backwards compatibility.

`UV_ENV_FILE`

added in 0.4.30

.env files from which to load environment variables when executing uv run commands.

`UV_EXCLUDE`

added in 0.9.8

Equivalent to the --excludes command-line argument. If set, uv will use this as the excludes file. Uses space-separated list of files.

`UV_EXCLUDE_NEWER`

added in 0.2.12

Equivalent to the --exclude-newer command-line argument. If set, uv will exclude distributions published after the specified date.

`UV_EXTRA_INDEX_URL`

added in 0.1.3

Equivalent to the --extra-index-url command-line argument. If set, uv will use this space-separated list of URLs as additional indexes when searching for packages. (Deprecated: use UV_INDEX instead.)

`UV_FIND_LINKS`

added in 0.4.19

Equivalent to the --find-links command-line argument. If set, uv will use this comma-separated list of additional locations to search for packages.

`UV_FORK_STRATEGY`

added in 0.5.9

Equivalent to the --fork-strategy argument. Controls version selection during universal resolution.

`UV_FROZEN`

added in 0.4.25

Equivalent to the --frozen command-line argument. If set, uv will run without updating the uv.lock file.

`UV_GITHUB_TOKEN`

added in 0.4.10

Equivalent to the --token argument for self update. A GitHub token for authentication.

`UV_GIT_LFS`

added in 0.5.19

Enables fetching files stored in Git LFS when installing a package from a Git repository.

`UV_HIDE_BUILD_OUTPUT`

added in 0.9.15

Suppress output from the build backend when building source distributions, even in the event of build failures.

`UV_HTTP_RETRIES`

added in 0.7.21

The number of retries for HTTP requests. (default: 3)

`UV_HTTP_TIMEOUT`

added in 0.1.7

Timeout (in seconds) for HTTP requests. (default: 30 s)

`UV_INDEX`

added in 0.4.23

Equivalent to the --index command-line argument. If set, uv will use this space-separated list of URLs as additional indexes when searching for packages.

`UV_INDEX_STRATEGY`

added in 0.1.29

Equivalent to the --index-strategy command-line argument.

For example, if set to unsafe-best-match, uv will consider versions of a given package available across all index URLs, rather than limiting its search to the first index URL that contains the package.

`UV_INDEX_URL`

added in 0.0.5

Equivalent to the --index-url command-line argument. If set, uv will use this URL as the default index when searching for packages. (Deprecated: use UV_DEFAULT_INDEX instead.)

`UV_INDEX_{name}_PASSWORD`

added in 0.4.23

Provides the HTTP Basic authentication password for a named index.

The name parameter is the name of the index. For example, given an index named foo, the environment variable key would be UV_INDEX_FOO_PASSWORD.

`UV_INDEX_{name}_USERNAME`

added in 0.4.23

Provides the HTTP Basic authentication username for a named index.

The name parameter is the name of the index. For example, given an index named foo, the environment variable key would be UV_INDEX_FOO_USERNAME.

`UV_INIT_BUILD_BACKEND`

added in 0.8.2

Equivalent to the --build-backend argument for uv init. Determines the default backend to use when creating a new project.

`UV_INSECURE_HOST`

added in 0.3.5

Equivalent to the --allow-insecure-host argument.

`UV_INSECURE_NO_ZIP_VALIDATION`

added in 0.8.6

Disable ZIP validation for streamed wheels and ZIP-based source distributions.

WARNING: Disabling ZIP validation can expose your system to security risks by bypassing integrity checks and allowing uv to install potentially malicious ZIP files. If uv rejects a ZIP file due to failing validation, it is likely that the file is malformed; consider filing an issue with the package maintainer.

`UV_INSTALLER_GHE_BASE_URL`

added in 0.5.0

The URL from which to download uv using the standalone installer and self update feature, in lieu of the default GitHub Enterprise URL.

`UV_INSTALLER_GITHUB_BASE_URL`

added in 0.5.0

The URL from which to download uv using the standalone installer and self update feature, in lieu of the default GitHub URL.

`UV_INSTALL_DIR`

added in 0.5.0

The directory in which to install uv using the standalone installer and self update feature. Defaults to ~/.local/bin.

`UV_ISOLATED`

added in 0.8.14

Equivalent to the --isolated command-line argument. If set, uv will avoid discovering a pyproject.toml or uv.toml file.

`UV_KEYRING_PROVIDER`

added in 0.1.19

Equivalent to the --keyring-provider command-line argument. If set, uv will use this value as the keyring provider.

`UV_LIBC`

added in 0.7.22

Overrides the environment-determined libc on linux systems when filling in the current platform within Python version requests. Options are: gnu, gnueabi, gnueabihf, musl, and none.

`UV_LINK_MODE`

added in 0.1.40

Equivalent to the --link-mode command-line argument. If set, uv will use this as a link mode.

`UV_LOCKED`

added in 0.4.25

Equivalent to the --locked command-line argument. If set, uv will assert that the uv.lock remains unchanged.

`UV_LOCK_TIMEOUT`

added in 0.9.4

The time in seconds uv waits for a file lock to become available.

Defaults to 300s (5 min).

`UV_LOG_CONTEXT`

added in 0.6.4

Add additional context and structure to log messages.

If logging is not enabled, e.g., with RUST_LOG or -v, this has no effect.