5.3 环境变量
11 分钟阅读
Environment variables
uv defines and respects the following environment variables:
UV_ASTRAL_MIRROR_URL
自 0.11.14 起新增
Replaces the https://releases.astral.sh base URL for all Astral-mirrored metadata and artifact downloads.
When set, uv uses only the configured mirror URL and does not fall back to GitHub or raw GitHub. Path components in the URL are preserved: only trailing slashes are trimmed before appending the normal path suffix (e.g., /github/versions/main/v1/uv.ndjson).
This is useful for proxy repositories (e.g., Artifactory, Nexus) that mirror releases.astral.sh.
More-specific sources take precedence: UV_PYTHON_INSTALL_MIRROR and python-install-mirror override this variable for CPython downloads, while UV_INSTALLER_GITHUB_BASE_URL and UV_INSTALLER_GHE_BASE_URL override this variable for uv self update.
UV_AZURE_ENDPOINT_URL
自 0.11.14 起新增
The URL to treat as an Azure Blob Storage endpoint. Requests to this endpoint will be signed using Azure credentials from the default credential chain, including Azure CLI credentials and workload identity.
UV_BREAK_SYSTEM_PACKAGES
自 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
自 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
自 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
自 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
自 0.7.22 起新增
Timeout (in seconds) for bytecode compilation.
UV_CONCURRENT_BUILDS
自 0.1.43 起新增
Sets the maximum number of source distributions that uv will build concurrently at any given time.
UV_CONCURRENT_CACHE_READS
自 0.11.29 起新增
Controls the number of threads used to read cached HTTP responses.
UV_CONCURRENT_DOWNLOADS
自 0.1.43 起新增
Sets the maximum number of in-flight concurrent downloads that uv will perform at any given time.
UV_CONCURRENT_INSTALLS
自 0.1.45 起新增
Controls the number of threads used when installing and unzipping packages.
UV_CONFIG_FILE
自 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
自 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
自 0.8.15 起新增
The directory for storage of credentials when using a plain text backend.
UV_CUSTOM_COMPILE_COMMAND
自 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
自 0.4.23 起新增
Equivalent to the --default-index command-line argument. If set, uv will use this index as the default index when searching for packages.
UV_DEV
自 0.8.7 起新增
Equivalent to the --dev command-line argument. If set, uv will include development dependencies.
UV_DOWNLOAD_URL
自 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
自 0.4.30 起新增
.env files from which to load environment variables when executing uv run commands.
UV_EXCLUDE
自 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
自 0.2.12 起新增
Equivalent to the --exclude-newer command-line argument. If set, uv will exclude distributions published after the specified date. Set to false to disable exclude-newer.
UV_EXTRA_INDEX_URL
自 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
自 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
自 0.5.9 起新增
Equivalent to the --fork-strategy argument. Controls version selection during universal resolution.
UV_FROZEN
自 0.4.25 起新增
Equivalent to the --frozen command-line argument. If set, uv will run without updating the uv.lock file.
UV_GCS_ENDPOINT_URL
自 0.9.26 起新增
The URL to treat as a GCS-compatible storage endpoint. Requests to this endpoint will be signed using Google Cloud authentication based on the GOOGLE_APPLICATION_CREDENTIALS environment variable or Application Default Credentials.
UV_GITHUB_TOKEN
自 0.4.10 起新增
Equivalent to the --token argument for self update. A GitHub token for authentication.
UV_GIT_LFS
自 0.5.19 起新增
Enables fetching files stored in Git LFS when installing a package from a Git repository.
UV_HIDE_BUILD_OUTPUT
自 0.9.15 起新增
Suppress output from the build backend when building source distributions, even in the event of build failures.
UV_HTTP_CONNECT_TIMEOUT
自 0.10.0 起新增
Timeout (in seconds) to connect to a server. (default: 10 s)
If UV_HTTP_TIMEOUT is lower than this value, UV_HTTP_TIMEOUT will be used instead.
UV_HTTP_RETRIES
自 0.7.21 起新增
The number of retries for HTTP requests. (default: 3)
UV_HTTP_TIMEOUT
自 0.1.7 起新增
Timeout (in seconds) for HTTP reads. (default: 30 s)
UV_INDEX
自 0.4.23 起新增
Equivalent to the --index command-line argument. If set, uv will use this space-separated list of additional indexes when searching for packages.
UV_INDEX_STRATEGY
自 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
自 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
自 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
自 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_BARE
自 0.10.7 起新增
Equivalent to the --bare argument for uv init. If set, uv will only create a pyproject.toml.
UV_INIT_BUILD_BACKEND
自 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
自 0.3.5 起新增
Equivalent to the --allow-insecure-host argument.
UV_INSECURE_NO_ZIP_VALIDATION
自 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
自 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.
This more-specific installer source takes precedence over UV_ASTRAL_MIRROR_URL for uv self update.
UV_INSTALLER_GITHUB_BASE_URL
自 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.
This more-specific installer source takes precedence over UV_ASTRAL_MIRROR_URL for uv self update.
UV_INSTALL_DIR
自 0.5.0 起新增
The directory in which to install uv using the standalone installer and self update feature. Defaults to ~/.local/bin.
UV_ISOLATED
自 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
自 0.1.19 起新增
Equivalent to the --keyring-provider command-line argument. If set, uv will use this value as the keyring provider.
UV_LIBC
自 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, musleabi, musleabihf, and none.
UV_LINK_MODE
自 0.1.40 起新增
Equivalent to the --link-mode command-line argument. If set, uv will use this as a link mode.
UV_LOCKED
自 0.4.25 起新增
Equivalent to the --locked command-line argument. If set, uv will assert that the uv.lock remains unchanged.
UV_LOCK_TIMEOUT
自 0.9.4 起新增
The time in seconds uv waits for a file lock to become available.
Defaults to 300s (5 min).
UV_LOG_CONTEXT
自 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_MALWARE_CHECK
自 0.11.16 起新增
Set to 1 to enable the automatic malware check that runs after uv sync.
When enabled, uv performs a lightweight check against the OSV database for known malware advisories after every lockfile sync. Set this variable to 0 to opt out.
UV_MALWARE_CHECK_URL
自 0.11.16 起新增
Override the vulnerability service URL for the automatic malware check.
Defaults to the OSV API endpoint (https://api.osv.dev/).
UV_MANAGED_PYTHON
自 0.6.8 起新增
Require use of uv-managed Python versions.
UV_NATIVE_TLS
自 0.1.19 起新增
Equivalent to the --native-tls command-line argument. If set to true, uv will load TLS certificates from the platform’s native certificate store instead of the bundled Mozilla root certificates. (Deprecated: use UV_SYSTEM_CERTS instead.)
UV_NO_BINARY
自 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
自 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
自 0.1.40 起新增
Equivalent to the --no-build command-line argument. If set, uv will not build source distributions. First-party packages, such as projects in the workspace, will still be built.
UV_NO_BUILD_ISOLATION
自 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
自 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. First-party packages, such as projects in the workspace, will still be built.
UV_NO_CACHE
自 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
自 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
自 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
自 0.8.7 起新增
Equivalent to the --no-dev command-line argument. If set, uv will exclude development dependencies.
UV_NO_EDITABLE
自 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
自 0.4.30 起新增
Ignore .env files when executing uv run commands.
UV_NO_GITHUB_FAST_PATH
自 0.7.13 起新增
Disable GitHub-specific requests that allow uv to skip git fetch in some circumstances.
UV_NO_GROUP
自 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
自 0.8.1 起新增
Disable Hugging Face authentication, even if HF_TOKEN is set.
UV_NO_INSTALLER_METADATA
自 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_INSTALL_LOCAL
自 0.11.20 起新增
Equivalent to the --no-install-local command-line argument. If set, uv will skip the current project, workspace members, and any other local (path or editable) packages, installing only remote dependencies.
UV_NO_INSTALL_PROJECT
自 0.11.20 起新增
Equivalent to the --no-install-project command-line argument. If set, uv will install the project’s dependencies but not the project itself.
UV_NO_INSTALL_WORKSPACE
自 0.11.20 起新增
Equivalent to the --no-install-workspace command-line argument. If set, uv will install workspace dependencies but not workspace members (including the current project).
UV_NO_MANAGED_PYTHON
自 0.6.8 起新增
Disable use of uv-managed Python versions.
UV_NO_MODIFY_PATH
自 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
自 0.2.28 起新增
Equivalent to the --no-progress command-line argument. Disables all progress output. For example, spinners and progress bars.
UV_NO_PROJECT
自 0.11.8 起新增
Equivalent to the --no-project command-line argument.
UV_NO_SOURCES
自 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_SOURCES_PACKAGE
自 0.9.26 起新增
Equivalent to the --no-sources-package command line argument. If set, uv will ignore the tool.uv.sources table for the given space-delimited list of packages.
UV_NO_SYNC
自 0.4.18 起新增
Equivalent to the --no-sync command-line argument. If set, uv will skip updating the environment.
UV_NO_SYSTEM_CONFIG
自 0.11.16 起新增
If set, uv will not read system-level configuration files.
UV_NO_VERIFY_HASHES
自 0.5.3 起新增
Equivalent to the --no-verify-hashes argument. Disables hash verification for requirements.txt files.
UV_NO_WRAP
自 0.0.5 起新增
Use to disable line wrapping for diagnostics.
UV_OFFLINE
自 0.5.9 起新增
Equivalent to the --offline command-line argument. If set, uv will disable network access.
UV_OVERRIDE
自 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
自 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
自 0.1.37 起新增
Equivalent to the --preview argument. Enables preview mode.
UV_PREVIEW_FEATURES
自 0.8.4 起新增
Equivalent to the --preview-features argument. Enables specific preview features.
UV_PROJECT
自 0.4.4 起新增
Equivalent to the --project command-line argument.
UV_PROJECT_ENVIRONMENT
自 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
自 0.4.30 起新增
Equivalent to the --check-url command-line argument in uv publish. Don’t upload a file if it already exists on the index. The value is the URL of the index.
UV_PUBLISH_INDEX
自 0.5.8 起新增
Equivalent to the --index command-line argument in uv publish. If set, uv will use the index with this name in the configuration for publishing.
UV_PUBLISH_NO_ATTESTATIONS
自 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
自 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
自 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
自 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
自 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
自 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
自 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
自 0.4.29 起新增
Specifies the directory to place links to installed, managed Python executables.
UV_PYTHON_CACHE_DIR
自 0.7.0 起新增
Specifies the directory for caching the archives of managed Python installations before installation.
UV_PYTHON_CPYTHON_BUILD
自 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
自 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
自 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
自 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
自 0.8.0 起新增
Whether to install the Python executable into the UV_PYTHON_BIN_DIR directory.
UV_PYTHON_INSTALL_DIR
自 0.2.22 起新增
Specifies the directory for storing managed Python installations.
UV_PYTHON_INSTALL_MIRROR
自 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.
This more-specific mirror takes precedence over UV_ASTRAL_MIRROR_URL for CPython downloads.
UV_PYTHON_INSTALL_REGISTRY
自 0.8.0 起新增
Whether to install the Python executable into the Windows registry.
UV_PYTHON_NO_REGISTRY
自 0.11.8 起新增
Disable use of the Windows registry for Python discovery and registration.
When set, uv will not discover Python interpreters from the Windows registry or Microsoft Store locations, and managed Python installations will not be registered in the Windows registry.
UV_PYTHON_PREFERENCE
自 0.3.2 起新增
Whether uv should prefer system or managed Python versions.
UV_PYTHON_PYODIDE_BUILD
自 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
自 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_PYTHON_SEARCH_PATH
自 0.11.8 起新增
Used to override PATH for Python executable discovery.
When set, uv will search for Python interpreters in the directories specified by this variable instead of PATH.
UV_REQUEST_TIMEOUT
自 0.1.6 起新增
Timeout (in seconds) for HTTP requests. Equivalent to UV_HTTP_TIMEOUT.
UV_REQUIRE_HASHES
自 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
自 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_RUN_RLIMIT_NOFILE
自 0.12.3 起新增
Sets the soft open-file descriptor limit for commands executed by uv run.
The limit is applied after uv prepares the environment and immediately before the command is spawned. The hard open-file descriptor limit remains unchanged. If the limit cannot be applied, uv exits with an error without running the command. Only supported on Unix.
UV_S3_ENDPOINT_URL
自 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
自 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
自 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_CERTS
自 0.11.0 起新增
Equivalent to the --system-certs command-line argument. If set to true, uv will load TLS certificates from the platform’s native certificate store instead of the bundled Mozilla root certificates.
UV_SYSTEM_PYTHON
自 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_TOOL_BIN_DIR
自 0.3.0 起新增
Specifies the “bin” directory for installing tool executables.
UV_TOOL_DIR
自 0.2.16 起新增
Specifies the directory where uv stores managed tools.
UV_TORCH_BACKEND
自 0.6.9 起新增
Equivalent to the --torch-backend command-line argument (e.g., cpu, cu126, or auto).
UV_UNMANAGED_INSTALL
自 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.
UV_UPLOAD_HTTP_TIMEOUT
自 0.9.1 起新增
Timeout (in seconds) for only upload HTTP requests. (default: 900 s)
UV_VENV_CLEAR
自 0.8.0 起新增
Equivalent to the --clear command-line argument. If set, uv will remove any existing files or directories at the target path.
UV_VENV_RELOCATABLE
自 0.10.8 起新增
Equivalent to the --relocatable command-line argument. If set, the virtual environment will be relocatable.
UV_VENV_SEED
自 0.5.21 起新增
Install seed packages (one or more of: pip, setuptools, and wheel) into the virtual environment created by uv venv.
Note that setuptools and wheel are not included in Python 3.12+ environments.
UV_WORKING_DIR
自 0.9.14 起新增
Equivalent to the --directory command-line argument. UV_WORKING_DIRECTORY (added in v0.9.1) is also supported for backwards compatibility.
Externally defined variables
uv also reads the following externally defined environment variables:
ALL_PROXY
自 0.1.38 起新增
General proxy for all network requests.
ANDROID_API_LEVEL
自 0.8.16 起新增
Used with --python-platform aarch64-linux-android and related variants to set the Android API level. (i.e., the minimum supported Android API level).
Defaults to 24.
APPDATA
自 0.1.42 起新增
Path to user-level configuration directory on Windows systems.
AWS_ACCESS_KEY_ID
自 0.8.21 起新增
The AWS access key ID to use when signing S3 requests.
AWS_CONFIG_FILE
自 0.8.21 起新增
The AWS config file to use when signing S3 requests.
AWS_DEFAULT_REGION
自 0.8.21 起新增
The default AWS region to use when signing S3 requests, if AWS_REGION is not set.
AWS_PROFILE
自 0.8.21 起新增
The AWS profile to use when signing S3 requests.
AWS_REGION
自 0.8.21 起新增
The AWS region to use when signing S3 requests.
AWS_SECRET_ACCESS_KEY
自 0.8.21 起新增
The AWS secret access key to use when signing S3 requests.
AWS_SESSION_TOKEN
自 0.8.21 起新增
The AWS session token to use when signing S3 requests.
AWS_SHARED_CREDENTIALS_FILE
自 0.8.21 起新增
The AWS shared credentials file to use when signing S3 requests.
BASH_VERSION
自 0.1.28 起新增
Used to detect Bash shell usage.
CLICOLOR_FORCE
自 0.1.32 起新增
Use to control color via anstyle.
COLUMNS
自 0.6.2 起新增
Overrides terminal width used for wrapping. This variable is not read by uv directly.
This is a quasi-standard variable, described, e.g., in ncurses(3x).
CONDA_DEFAULT_ENV
自 0.5.0 起新增
Used to determine the name of the active Conda environment.
CONDA_PREFIX
自 0.0.5 起新增
Used to detect the path of an active Conda environment.
DEPENDABOT
自 0.9.11 起新增
Used to determine if we’re running in Dependabot.
FISH_VERSION
自 0.1.28 起新增
Used to detect Fish shell usage.
FORCE_COLOR
自 0.2.7 起新增
Forces colored output regardless of terminal support.
See force-color.org.
GITHUB_ACTIONS
自 0.4.16 起新增
Indicates that the current process is running in GitHub Actions.
uv publish may attempt trusted publishing flows when set to true.
GITLAB_CI
自 0.8.18 起新增
Indicates that the current process is running in GitLab CI.
uv publish may attempt trusted publishing flows when set to true.
HF_TOKEN
自 0.8.1 起新增
Authentication token for Hugging Face requests. When set, uv will use this token when making requests to https://huggingface.co/ and any subdomains.
HOME
自 0.0.5 起新增
The standard HOME env var.
HTTPS_PROXY
自 0.1.38 起新增
Proxy for HTTPS requests.
HTTP_PROXY
自 0.1.38 起新增
Proxy for HTTP requests.
HTTP_TIMEOUT
自 0.1.7 起新增
Timeout (in seconds) for HTTP requests. Equivalent to UV_HTTP_TIMEOUT.
IPHONEOS_DEPLOYMENT_TARGET
自 0.8.16 起新增
Used with --python-platform arm64-apple-ios and related variants to set the deployment target (i.e., the minimum supported iOS version).
Defaults to 13.0.
JPY_SESSION_NAME
自 0.2.6 起新增
Used to detect when running inside a Jupyter notebook.
KSH_VERSION
自 0.2.33 起新增
Used to detect Ksh shell usage.
LOCALAPPDATA
自 0.3.3 起新增
Used to look for Microsoft Store Pythons installations.
MACOSX_DEPLOYMENT_TARGET
自 0.1.42 起新增
Used with --python-platform macos and related variants to set the deployment target (i.e., the minimum supported macOS version).
Defaults to 13.0, the least-recent non-EOL macOS version at time of writing.
NETRC
自 0.1.16 起新增
Use to set the .netrc file location.
NO_COLOR
自 0.2.7 起新增
Disables colored output (takes precedence over FORCE_COLOR).
See no-color.org.
NO_PROXY
自 0.1.38 起新增
Comma-separated list of hostnames (e.g., example.com) and/or patterns (e.g., 192.168.1.0/24) that should bypass the proxy.
NU_VERSION
自 0.1.16 起新增
Used to detect NuShell usage.
PAGER
自 0.4.18 起新增
The standard PAGER posix env var. Used by uv to configure the appropriate pager.
PATH
自 0.0.5 起新增
The standard PATH env var.
PROMPT
自 0.1.16 起新增
Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
PSModulePath
自 0.10.0 起新增
Used to detect PowerShell usage (set by PowerShell on all platforms).
PWD
自 0.0.5 起新增
The standard PWD posix env var.
PYC_INVALIDATION_MODE
自 0.1.7 起新增
The validation modes to use when run with --compile.
See PycInvalidationMode.
PYTHONPATH
自 0.1.22 起新增
Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules).
PYX_API_KEY
自 0.8.15 起新增
The pyx API key (e.g., sk-pyx-...).
PYX_AUTH_TOKEN
自 0.8.15 起新增
The pyx authentication token (e.g., eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...), as output by uv auth token.
RUFF
自 0.11.22 起新增
The path to the Ruff binary used by uv format.
RUST_BACKTRACE
自 0.7.22 起新增
If set, it can be used to display more stack trace details when a panic occurs. This is used by uv particularly on windows to show more details during a platform exception.
For example:
- RUST_BACKTRACE=1 will print a short backtrace.
- RUST_BACKTRACE=full will print a full backtrace.
See the Rust backtrace documentation for more.
RUST_LOG
自 0.0.5 起新增
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.
RUST_MIN_STACK
自 0.5.19 起新增
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.
Prefer setting UV_STACK_SIZE, since RUST_MIN_STACK also affects subprocesses, such as build backends that use Rust code.
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(RUST_MIN_STACK, 1MB).
SHELL
自 0.1.16 起新增
The standard SHELL posix env var.
SSL_CERT_DIR
自 0.9.10 起新增
Path to a directory containing PEM-encoded CA certificate files for TLS connections.
Multiple entries are supported, separated using a platform-specific delimiter (: on Unix, ; on Windows).
Certificates are usually stored with .pem, .crt, or .cer extensions, but uv will attempt to read a certificate from any regular file in the provided SSL_CERT_DIR.
Files that cannot be parsed as PEM certificates are ignored. uv resolves symlinks and ignores dangling symlinks.
Only PEM-encoded files are supported, i.e., DER-encoded files are not supported.
When set, this overrides the default certificate source (bundled Mozilla roots or system certificates). Only the certificates in this directory will be trusted.
SSL_CERT_FILE
自 0.1.14 起新增
Path to a CA certificate bundle file for TLS connections.
Requires a PEM-encoded certificate file (e.g., certs.pem, ca-bundle.crt). DER-encoded files are not supported.
When set, this overrides the default certificate source (bundled Mozilla roots or system certificates). Only the certificates in this file will be trusted.
SSL_CLIENT_CERT
自 0.2.11 起新增
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
自 0.4.26 起新增
Path to system-level configuration directory on Windows systems.
TRACING_DURATIONS_FILE
自 0.0.5 起新增
Use to create the tracing durations file via the tracing-durations-export feature.
TY
自 0.11.22 起新增
The path to the ty binary used by uv check.
USERPROFILE
自 0.0.5 起新增
Path to root directory of user’s profile on Windows systems.
UV
自 0.6.0 起新增
The path to the binary that was used to invoke uv.
This is propagated to all subprocesses spawned by uv.
If the executable was invoked through a symbolic link, some platforms will return the path of the symbolic link and other platforms will return the path of the symbolic link’s target.
See https://doc.rust-lang.org/std/env/fn.current_exe.html#security for security considerations.
VIRTUAL_ENV
自 0.0.5 起新增
Used to detect an activated virtual environment.
VIRTUAL_ENV_DISABLE_PROMPT
自 0.0.5 起新增
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
自 0.2.16 起新增
Path to directory where executables are installed.
XDG_CACHE_HOME
自 0.1.17 起新增
Path to cache directory on Unix systems.
XDG_CONFIG_DIRS
自 0.4.26 起新增
Path to system-level configuration directory on Unix systems.
XDG_CONFIG_HOME
自 0.1.34 起新增
Path to user-level configuration directory on Unix systems.
XDG_DATA_HOME
自 0.2.16 起新增
Path to directory for storing managed Python installations and tools.
ZDOTDIR
自 0.2.25 起新增
Used to determine which .zshenv to use when Zsh is being used.
ZSH_VERSION
自 0.1.28 起新增
Used to detect Zsh shell usage.
_CONDA_ROOT
自 0.8.18 起新增
Used to determine the root install path of Conda.