Environment variables

uv defines and respects the following environment variables:

`UV_BREAK_SYSTEM_PACKAGES`

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`

Equivalent to the --build-constraint 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`

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`

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

`UV_CONCURRENT_BUILDS`

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

`UV_CONCURRENT_DOWNLOADS`

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

`UV_CONCURRENT_INSTALLS`

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

`UV_CONFIG_FILE`

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`

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

`UV_CUSTOM_COMPILE_COMMAND`

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`

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

`UV_ENV_FILE`

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

`UV_EXCLUDE_NEWER`

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

`UV_EXTRA_INDEX_URL`

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`

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`

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

`UV_FROZEN`

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

`UV_GITHUB_TOKEN`

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

`UV_HTTP_TIMEOUT`

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

`UV_INDEX`

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`

Equivalent to the --index-strategy command-line argument. For example, if set to unsafe-any-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`

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`

Generates the environment variable key for the HTTP Basic authentication password.

`UV_INDEX_{name}_USERNAME`

Generates the environment variable key for the HTTP Basic authentication username.

`UV_INSECURE_HOST`

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

`UV_INSTALLER_GHE_BASE_URL`

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`

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`

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

`UV_KEYRING_PROVIDER`

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

`UV_LINK_MODE`

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

`UV_LOCKED`

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

`UV_NATIVE_TLS`

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_BUILD_ISOLATION`

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

`UV_NO_CACHE`

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

`UV_NO_CONFIG`

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_ENV_FILE`

Ignore .env files when executing uv run commands.

`UV_NO_INSTALLER_METADATA`

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

`UV_NO_PROGRESS`

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

`UV_NO_SYNC`

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

`UV_NO_VERIFY_HASHES`

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

`UV_NO_WRAP`

Use to disable line wrapping for diagnostics.

`UV_OFFLINE`

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

`UV_OVERRIDE`

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

`UV_PRERELEASE`

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

`UV_PREVIEW`

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

`UV_PROJECT_ENVIRONMENT`

Specifies the path to the directory to use for a project virtual environment. See the project documentation for more details.

`UV_PUBLISH_CHECK_URL`

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

`UV_PUBLISH_INDEX`

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_PASSWORD`

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

`UV_PUBLISH_TOKEN`

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`

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`

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

`UV_PYPY_INSTALL_MIRROR`

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`

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`

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

`UV_PYTHON_DOWNLOADS`

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

`UV_PYTHON_INSTALL_DIR`

Specifies the directory for storing managed Python installations.

`UV_PYTHON_INSTALL_MIRROR`

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_PREFERENCE`

Equivalent to the --python-preference command-line argument. Whether uv should prefer system or managed Python versions.

`UV_REQUEST_TIMEOUT`

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

`UV_REQUIRE_HASHES`

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`

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_STACK_SIZE`

Use to increase the stack size used by uv in debug builds on Windows.

`UV_SYSTEM_PYTHON`

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_TOOL_BIN_DIR`

Specifies the "bin" directory for installing tool executables.

`UV_TOOL_DIR`

Specifies the directory where uv stores managed tools.

`UV_UNMANAGED_INSTALL`

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

Externally defined variables

uv also reads the following externally defined environment variables:

`ACTIONS_ID_TOKEN_REQUEST_TOKEN`

Used for trusted publishing via uv publish. Contains the oidc request token.

`ACTIONS_ID_TOKEN_REQUEST_URL`

Used for trusted publishing via uv publish. Contains the oidc token url.

`ALL_PROXY`

General proxy for all network requests.

`BASH_VERSION`

Used to detect Bash shell usage.

`CLICOLOR_FORCE`

Use to control color via anstyle.

`CONDA_DEFAULT_ENV`

Used to determine if an active Conda environment is the base environment or not.

`CONDA_PREFIX`

Used to detect an activated Conda environment.

`FISH_VERSION`

Used to detect Fish shell usage.

`FORCE_COLOR`

Forces colored output regardless of terminal support.

See force-color.org.

`GITHUB_ACTIONS`

Used for trusted publishing via uv publish.

`HOME`

The standard HOME env var.

`HTTPS_PROXY`

Proxy for HTTPS requests.

`HTTP_PROXY`

Proxy for HTTP requests.

`HTTP_TIMEOUT`

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

`INSTALLER_NO_MODIFY_PATH`

Avoid modifying the PATH environment variable when installing uv using the standalone installer and self update feature.

`JPY_SESSION_NAME`

Used to detect when running inside a Jupyter notebook.

`KSH_VERSION`

Used to detect Ksh shell usage.

`LOCALAPPDATA`

Used to look for Microsoft Store Pythons installations.

`MACOSX_DEPLOYMENT_TARGET`

Used with --python-platform macos and related variants to set the deployment target (i.e., the minimum supported macOS version).

Defaults to 12.0, the least-recent non-EOL macOS version at time of writing.

`NETRC`

Use to set the .netrc file location.

`NO_COLOR`

Disables colored output (takes precedence over FORCE_COLOR).

See no-color.org.

`NU_VERSION`

Used to detect NuShell usage.

The standard PAGER posix env var. Used by uv to configure the appropriate pager.

`PATH`

The standard PATH env var.

`PROMPT`

Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).

`PWD`

The standard PWD posix env var.

`PYC_INVALIDATION_MODE`

The validation modes to use when run with --compile.

See PycInvalidationMode.

`PYTHONPATH`

Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules).

`RUST_LOG`

If set, uv will use this value as the log level for its --verbose output. Accepts any filter compatible with the tracing_subscriber crate. For example: * RUST_LOG=uv=debug is the equivalent of adding --verbose to the command line * RUST_LOG=trace will enable trace-level logging.

See the tracing documentation for more.