uv/docs/configuration/environment.md

# Environment variables

uv respects the following environment variables:

- `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_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_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_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_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_NO_CACHE`: Equivalent to the `--no-cache` command-line argument. If set, uv will not use the
  cache for any operations.
- `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_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to
  `allow`, uv will allow pre-release versions for all dependencies.
- `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_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will use
  this Python interpreter for all operations.
- `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_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_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_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_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_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_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_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as
  a link mode.
- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, uv will
  skip isolation when building source distributions.
- `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_KEYRING_PROVIDER`: Equivalent to the `--keyring-provider` command-line argument. If set, uv
  will use this value as the keyring provider.
- `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_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_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will
  exclude distributions published after the specified date.
- `UV_PYTHON_PREFERENCE`: Equivalent to the `--python-preference` command-line argument. Whether uv
  should prefer system or managed Python versions.
- `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_COMPILE_BYTECODE`: Equivalent to the `--compile-bytecode` command-line argument. If set, uv
  will compile Python source files to bytecode after installation.
- `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_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_USERNAME`: Equivalent to the `--username` command-line argument in `uv publish`. If
  set, uv will use this username 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_CHECK_URL`: Don't upload a file if it already exists on the index. The value is the URL of the index.
- `UV_NO_SYNC`: Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating
  the environment.
- `UV_LOCKED`: Equivalent to the `--locked` command-line argument. If set, uv will assert that the
  `uv.lock` remains unchanged.
- `UV_FROZEN`: Equivalent to the `--frozen` command-line argument. If set, uv will run without
  updating the `uv.lock` file.
- `UV_PREVIEW`: Equivalent to the `--preview` argument. Enables preview mode.
- `UV_GITHUB_TOKEN`: Equivalent to the `--token` argument for self update. A GitHub token for authentication.
- `UV_VERIFY_HASHES`: Equivalent to the `--verify-hashes` argument. Verifies included hashes.
- `UV_INSECURE_HOST`: Equivalent to the `--allow-insecure-host` argument.
- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will
  perform at any given time.
- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build
  concurrently at any given time.
- `UV_CONCURRENT_INSTALLS`: Controls the number of threads used when installing and unzipping
  packages.
- `UV_TOOL_DIR`: Specifies the directory where uv stores managed tools.
- `UV_TOOL_BIN_DIR`: Specifies the "bin" directory for installing tool executables.
- `UV_PROJECT_ENVIRONMENT`: Specifies the path to the directory to use for a project virtual environment.
  See the [project documentation](../concepts/projects.md#configuring-the-project-environment-path)
  for more details.
- `UV_PYTHON_BIN_DIR`: Specifies the directory to place links to installed, managed Python executables.
- `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_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_NO_WRAP`: Use to disable line wrapping for diagnostics.
- `UV_STACK_SIZE`: Use to control the stack size used by uv. Typically more relevant for Windows in debug mode.
- `UV_INDEX_{name}_USERNAME`: Generates the environment variable key for the HTTP Basic authentication username.
- `UV_INDEX_{name}_PASSWORD`: Generates the environment variable key for the HTTP Basic authentication password.
- `XDG_CONFIG_DIRS`: Path to system-level configuration directory on Unix systems.
- `SYSTEMDRIVE`: Path to system-level configuration directory on Windows systems.
- `XDG_CONFIG_HOME`: Path to user-level configuration directory on Unix systems.
- `XDG_CACHE_HOME`: Path to cache directory on Unix systems.
- `XDG_DATA_HOME`: Path to directory for storing managed Python installations and tools.
- `XDG_BIN_HOME`: Path to directory where executables are installed.
- `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.
- `HTTP_PROXY`: Proxy for HTTP requests.
- `HTTPS_PROXY`: Proxy for HTTPS requests.
- `ALL_PROXY`: General proxy for all network requests.
- `UV_HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. (default: 30 s)
- `UV_REQUEST_TIMEOUT`: Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`.
- `HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`.
- `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).
- `VIRTUAL_ENV`: Used to detect an activated virtual environment.
- `CONDA_PREFIX`: Used to detect an activated Conda 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.
- `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
- `NU_VERSION`: Used to detect `NuShell` usage.
- `FISH_VERSION`: Used to detect Fish shell usage.
- `BASH_VERSION`: Used to detect Bash shell usage.
- `ZSH_VERSION`: Used to detect Zsh shell usage.
- `ZDOTDIR`: Used to determine which `.zshenv` to use when Zsh is being used.
- `KSH_VERSION`: Used to detect Ksh shell usage.
- `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.
- `NO_COLOR`: Disables colored output (takes precedence over `FORCE_COLOR`).
  See [no-color.org](https://no-color.org).
- `UV_NO_PROGRESS`: Disables all progress output. For example, spinners and progress bars.
- `FORCE_COLOR`: Forces colored output regardless of terminal support.
  See [force-color.org](https://force-color.org).
- `CLICOLOR_FORCE`: Use to control color via `anstyle`.
- `PATH`: The standard `PATH` env var.
- `HOME`: The standard `HOME` env var.
- `SHELL`: The standard `SHELL` posix env var.
- `PWD`: The standard `PWD` posix env var.
- `LOCALAPPDATA`: Used to look for Microsoft Store Pythons installations.
- `GIT_DIR`: Path to the `.git` directory. Ignored by `uv` when performing fetch.
- `GIT_WORK_TREE`: Path to the git working tree. Ignored by `uv` when performing fetch.
- `GIT_INDEX_FILE`: Path to the index file for staged changes. Ignored by `uv` when performing fetch.
- `GIT_OBJECT_DIRECTORY`: Path to where git object files are located. Ignored by `uv` when performing fetch.
- `GIT_ALTERNATE_OBJECT_DIRECTORIES`: Alternate locations for git objects. Ignored by `uv` when performing fetch.
- `GIT_CEILING_DIRECTORIES`: Used in tests for better git isolation.
  For example, we run some tests in ~/.local/share/uv/tests.
  And if the user's `$HOME` directory is a git repository,
  this will change the behavior of some tests. Setting
  `GIT_CEILING_DIRECTORIES=/home/andrew/.local/share/uv/tests` will
  prevent git from crawling up the directory tree past that point to find
  parent git repositories.
- `GITHUB_ACTIONS`: Used for trusted publishing via `uv publish`.
- `ACTIONS_ID_TOKEN_REQUEST_URL`: Used for trusted publishing via `uv publish`. Contains the oidc token url.
- `ACTIONS_ID_TOKEN_REQUEST_TOKEN`: Used for trusted publishing via `uv publish`. Contains the oidc request token.
- `PYTHONIOENCODING`: Sets the encoding for standard I/O streams (e.g., PYTHONIOENCODING=utf-8).
- `PYTHONUNBUFFERED`: Forces unbuffered I/O streams, equivalent to `-u` in Python.
- `PYTHONUTF8`: Enables UTF-8 mode for Python, equivalent to `-X utf8`.
- `PYTHONPATH`: Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules).
- `CI`: Typically set by CI runners, used to detect a CI runner.
- `NETRC`: Use to set the .netrc file location.
- `PAGER`: The standard `PAGER` posix env var. Used by `uv` to configure the appropriate pager.
- `JPY_SESSION_NAME`: Used to detect when running inside a Jupyter notebook.
- `TRACING_DURATIONS_TEST_ROOT`: Use to create the tracing root directory via the `tracing-durations-export` feature.
- `TRACING_DURATIONS_FILE`: Use to create the tracing durations file via the `tracing-durations-export` feature.
- `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=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.