uv/docs/configuration/environment.md

# 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_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_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_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](../concepts/projects/config.md#project-environment-path)
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_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](https://downloads.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`](../reference/settings.md#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
[`python-build-standalone`](https://github.com/indygreg/python-build-standalone).
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/indygreg/python-build-standalone/releases/download` in, e.g.,
`https://github.com/indygreg/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](https://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](https://no-color.org).

### `NU_VERSION`

Used to detect `NuShell` usage.

### `PAGER`

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`](https://docs.python.org/3/library/py_compile.html#py_compile.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](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
for more.

### `SHELL`

The standard `SHELL` posix env var.

### `SSL_CERT_FILE`

Custom certificate bundle file path for SSL connections.

### `SSL_CLIENT_CERT`

If set, uv will use this file for mTLS authentication.
This should be a single file containing both the certificate and the private key in PEM format.

### `SYSTEMDRIVE`

Path to system-level configuration directory on Windows systems.

### `TRACING_DURATIONS_FILE`

Use to create the tracing durations file via the `tracing-durations-export` feature.

### `VIRTUAL_ENV`

Used to detect an activated virtual environment.

### `VIRTUAL_ENV_DISABLE_PROMPT`

If set to `1` before a virtual environment is activated, then the
virtual environment name will not be prepended to the terminal prompt.

### `XDG_BIN_HOME`

Path to directory where executables are installed.

### `XDG_CACHE_HOME`

Path to cache directory on Unix systems.

### `XDG_CONFIG_DIRS`

Path to system-level configuration directory on Unix systems.

### `XDG_CONFIG_HOME`

Path to user-level configuration directory on Unix systems.

### `XDG_DATA_HOME`

Path to directory for storing managed Python installations and tools.

### `ZDOTDIR`

Used to determine which `.zshenv` to use when Zsh is being used.

### `ZSH_VERSION`

Used to detect Zsh shell usage.