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.

`UV_MANAGED_PYTHON`

added in 0.6.8

Require use of uv-managed Python versions.

`UV_NATIVE_TLS`

added in 0.1.19

Equivalent to the --native-tls command-line argument. If set to true, uv will use the system's trust store instead of the bundled webpki-roots crate.

`UV_NO_BINARY`

added in 0.5.30

Equivalent to the --no-binary command-line argument. If set, uv will install all packages from source. The resolver will still use pre-built wheels to extract package metadata, if available.

`UV_NO_BINARY_PACKAGE`

added in 0.5.30

Equivalent to the --no-binary-package command line argument. If set, uv will not use pre-built wheels for the given space-delimited list of packages.

`UV_NO_BUILD`

added in 0.1.40

Equivalent to the --no-build command-line argument. If set, uv will not build source distributions.

`UV_NO_BUILD_ISOLATION`

added in 0.1.40

Equivalent to the --no-build-isolation command-line argument. If set, uv will skip isolation when building source distributions.

`UV_NO_BUILD_PACKAGE`

added in 0.6.5

Equivalent to the --no-build-package command line argument. If set, uv will not build source distributions for the given space-delimited list of packages.

`UV_NO_CACHE`

added in 0.1.2

Equivalent to the --no-cache command-line argument. If set, uv will not use the cache for any operations.

`UV_NO_CONFIG`

added in 0.2.30

Equivalent to the --no-config command-line argument. If set, uv will not read any configuration files from the current directory, parent directories, or user configuration directories.

`UV_NO_DEFAULT_GROUPS`

added in 0.9.9

Equivalent to the --no-default-groups command-line argument. If set, uv will not select the default dependency groups defined in tool.uv.default-groups.

`UV_NO_DEV`

added in 0.8.7

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

`UV_NO_EDITABLE`

added in 0.6.15

Equivalent to the --no-editable command-line argument. If set, uv installs or exports any editable dependencies, including the project and any workspace members, as non-editable.

`UV_NO_ENV_FILE`

added in 0.4.30

Ignore .env files when executing uv run commands.

`UV_NO_GITHUB_FAST_PATH`

added in 0.7.13

Disable GitHub-specific requests that allow uv to skip git fetch in some circumstances.

`UV_NO_GROUP`

added in 0.9.8

Equivalent to the --no-group command-line argument. If set, uv will disable the specified dependency groups for the given space-delimited list of packages.

`UV_NO_HF_TOKEN`

added in 0.8.1

Disable Hugging Face authentication, even if HF_TOKEN is set.

`UV_NO_INSTALLER_METADATA`

added in 0.5.7

Skip writing uv installer metadata files (e.g., INSTALLER, REQUESTED, and direct_url.json) to site-packages .dist-info directories.

`UV_NO_MANAGED_PYTHON`

added in 0.6.8

Disable use of uv-managed Python versions.

`UV_NO_MODIFY_PATH`

added in 0.8.4

Avoid modifying the PATH environment variable when installing uv using the standalone installer and self update feature. INSTALLER_NO_MODIFY_PATH is also supported as an alias, for backwards compatibility.

`UV_NO_PROGRESS`

added in 0.2.28

Equivalent to the --no-progress command-line argument. Disables all progress output. For example, spinners and progress bars.

`UV_NO_SOURCES`

added in 0.9.8

Equivalent to the --no-sources command-line argument. If set, uv will ignore [tool.uv.sources] annotations when resolving dependencies.

`UV_NO_SYNC`

added in 0.4.18

Equivalent to the --no-sync command-line argument. If set, uv will skip updating the environment.

`UV_NO_VERIFY_HASHES`

added in 0.5.3

Equivalent to the --no-verify-hashes argument. Disables hash verification for requirements.txt files.

`UV_NO_WRAP`

added in 0.0.5

Use to disable line wrapping for diagnostics.

`UV_OFFLINE`

added in 0.5.9

Equivalent to the --offline command-line argument. If set, uv will disable network access.

`UV_OVERRIDE`

added in 0.2.22

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

`UV_PRERELEASE`

added in 0.1.16

Equivalent to the --prerelease command-line argument. For example, if set to allow, uv will allow pre-release versions for all dependencies.

`UV_PREVIEW`

added in 0.1.37

Equivalent to the --preview argument. Enables preview mode.

`UV_PREVIEW_FEATURES`

added in 0.8.4

Equivalent to the --preview-features argument. Enables specific preview features.

`UV_PROJECT`

added in 0.4.4

Equivalent to the --project command-line argument.

`UV_PROJECT_ENVIRONMENT`

added in 0.4.4

Specifies the path to the directory to use for a project virtual environment.

See the project documentation for more details.

`UV_PUBLISH_CHECK_URL`

added in 0.4.30

Don't upload a file if it already exists on the index. The value is the URL of the index.

`UV_PUBLISH_INDEX`

added in 0.5.8

Equivalent to the --index command-line argument in uv publish. If set, uv the index with this name in the configuration for publishing.

`UV_PUBLISH_NO_ATTESTATIONS`

added in 0.9.12

Equivalent to the --no-attestations command-line argument in uv publish. If set, uv will skip uploading any collected attestations for the published distributions.

`UV_PUBLISH_PASSWORD`

added in 0.4.16

Equivalent to the --password command-line argument in uv publish. If set, uv will use this password for publishing.

`UV_PUBLISH_TOKEN`

added in 0.4.16

Equivalent to the --token command-line argument in uv publish. If set, uv will use this token (with the username __token__) for publishing.

`UV_PUBLISH_URL`

added in 0.4.16

Equivalent to the --publish-url command-line argument. The URL of the upload endpoint of the index to use with uv publish.

`UV_PUBLISH_USERNAME`

added in 0.4.16

Equivalent to the --username command-line argument in uv publish. If set, uv will use this username for publishing.

`UV_PYPY_INSTALL_MIRROR`

added in 0.2.35

Managed PyPy installations are downloaded from python.org.

This variable can be set to a mirror URL to use a different source for PyPy installations. The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2. Distributions can be read from a local directory by using the file:// URL scheme.

`UV_PYTHON`

added in 0.1.40

Equivalent to the --python command-line argument. If set to a path, uv will use this Python interpreter for all operations.

`UV_PYTHON_BIN_DIR`

added in 0.4.29

Specifies the directory to place links to installed, managed Python executables.

`UV_PYTHON_CACHE_DIR`

added in 0.7.0

Specifies the directory for caching the archives of managed Python installations before installation.

`UV_PYTHON_CPYTHON_BUILD`

added in 0.8.14

Pin managed CPython versions to a specific build version.

For CPython, this should be the build date (e.g., "20250814").

`UV_PYTHON_DOWNLOADS`

added in 0.3.2

Equivalent to the python-downloads setting and, when disabled, the --no-python-downloads option. Whether uv should allow Python downloads.

`UV_PYTHON_DOWNLOADS_JSON_URL`

added in 0.6.13

Managed Python installations information is hardcoded in the uv binary.

This variable can be set to a local path or URL pointing to a JSON list of Python installations to override the hardcoded list.

This allows customizing the URLs for downloads or using slightly older or newer versions of Python than the ones hardcoded into this build of uv.

`UV_PYTHON_GRAALPY_BUILD`

added in 0.8.14

Pin managed GraalPy versions to a specific build version.

For GraalPy, this should be the GraalPy version (e.g., "24.2.2").

`UV_PYTHON_INSTALL_BIN`

added in 0.8.0

Whether to install the Python executable into the UV_PYTHON_BIN_DIR directory.

`UV_PYTHON_INSTALL_DIR`

added in 0.2.22

Specifies the directory for storing managed Python installations.

`UV_PYTHON_INSTALL_MIRROR`

added in 0.2.35

Managed Python installations are downloaded from the Astral python-build-standalone project.

This variable can be set to a mirror URL to use a different source for Python installations. The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz. Distributions can be read from a local directory by using the file:// URL scheme.

`UV_PYTHON_INSTALL_REGISTRY`

added in 0.8.0

Whether to install the Python executable into the Windows registry.

`UV_PYTHON_PREFERENCE`

added in 0.3.2

Whether uv should prefer system or managed Python versions.

`UV_PYTHON_PYODIDE_BUILD`

added in 0.8.14

Pin managed Pyodide versions to a specific build version.

For Pyodide, this should be the Pyodide version (e.g., "0.28.1").

`UV_PYTHON_PYPY_BUILD`

added in 0.8.14

Pin managed PyPy versions to a specific build version.

For PyPy, this should be the PyPy version (e.g., "7.3.20").

`UV_REQUEST_TIMEOUT`

added in 0.1.6

Timeout (in seconds) for HTTP requests. Equivalent to UV_HTTP_TIMEOUT.

`UV_REQUIRE_HASHES`

added in 0.1.34

Equivalent to the --require-hashes command-line argument. If set to true, uv will require that all dependencies have a hash specified in the requirements file.

`UV_RESOLUTION`

added in 0.1.27

Equivalent to the --resolution command-line argument. For example, if set to lowest-direct, uv will install the lowest compatible versions of all direct dependencies.

`UV_S3_ENDPOINT_URL`

added in 0.8.21

The URL to treat as an S3-compatible storage endpoint. Requests to this endpoint will be signed using AWS Signature Version 4 based on the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE, and AWS_CONFIG_FILE environment variables.

`UV_SKIP_WHEEL_FILENAME_CHECK`

added in 0.8.23

Avoid verifying that wheel filenames match their contents when installing wheels. This is not recommended, as wheels with inconsistent filenames should be considered invalid and corrected by the relevant package maintainers; however, this option can be used to work around invalid artifacts in rare cases.

`UV_STACK_SIZE`

added in 0.0.5

Use to set the stack size used by uv.

The value is in bytes, and if both UV_STACK_SIZE are RUST_MIN_STACK unset, uv uses a 4MB (4194304) stack. UV_STACK_SIZE takes precedence over RUST_MIN_STACK.

Unlike the normal RUST_MIN_STACK semantics, this can affect main thread stack size, because we actually spawn our own main2 thread to work around the fact that Windows' real main thread is only 1MB. That thread has size max(UV_STACK_SIZE, 1MB).

`UV_SYSTEM_PYTHON`

added in 0.1.18

Equivalent to the --system command-line argument. If set to true, uv will use the first Python interpreter found in the system PATH.

WARNING: UV_SYSTEM_PYTHON=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_TEST_NO_HTTP_RETRY_DELAY`

added in 0.7.21

Used to disable delay for HTTP retries in tests.

`UV_TOOL_BIN_DIR`

added in 0.3.0

Specifies the "bin" directory for installing tool executables.

`UV_TOOL_DIR`

added in 0.2.16

Specifies the directory where uv stores managed tools.

`UV_TORCH_BACKEND`

added in 0.6.9

Equivalent to the --torch-backend command-line argument (e.g., cpu, cu126, or auto).

`UV_UNMANAGED_INSTALL`

added in 0.5.0

Used ephemeral environments like CI to install uv to a specific path while preventing the installer from modifying shell profiles or environment variables.