Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve some env var document #10887

Merged
merged 1 commit into from
Jan 23, 2025
Merged

Improve some env var document #10887

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 22 additions & 7 deletions crates/uv-static/src/env_vars.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ impl EnvVars {

/// 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.
Expand All @@ -63,6 +64,7 @@ impl EnvVars {

/// 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.
Expand All @@ -72,9 +74,11 @@ impl EnvVars {
/// use the system's trust store instead of the bundled `webpki-roots` crate.
pub const UV_NATIVE_TLS: &'static str = "UV_NATIVE_TLS";

/// 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.
/// 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.
pub const UV_INDEX_STRATEGY: &'static str = "UV_INDEX_STRATEGY";

/// Equivalent to the `--require-hashes` command-line argument. If set to `true`,
Expand Down Expand Up @@ -102,6 +106,7 @@ impl EnvVars {
pub const UV_NO_BUILD_ISOLATION: &'static str = "UV_NO_BUILD_ISOLATION";

/// 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.
Expand Down Expand Up @@ -208,6 +213,7 @@ impl EnvVars {
pub const UV_TOOL_BIN_DIR: &'static str = "UV_TOOL_BIN_DIR";

/// 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.
pub const UV_PROJECT_ENVIRONMENT: &'static str = "UV_PROJECT_ENVIRONMENT";
Expand All @@ -220,14 +226,16 @@ impl EnvVars {

/// Managed Python installations are downloaded from the Astral
/// [`python-build-standalone`](https://github.com/astral-sh/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.
pub const UV_PYTHON_INSTALL_MIRROR: &'static str = "UV_PYTHON_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
/// 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`.
Expand Down Expand Up @@ -255,13 +263,19 @@ impl EnvVars {
/// Use to disable line wrapping for diagnostics.
pub const UV_NO_WRAP: &'static str = "UV_NO_WRAP";

/// Generates the environment variable key for the HTTP Basic authentication username.
/// 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`.
#[attr_env_var_pattern("UV_INDEX_{name}_USERNAME")]
pub fn index_username(name: &str) -> String {
format!("UV_INDEX_{name}_USERNAME")
}

/// Generates the environment variable key for the HTTP Basic authentication password.
/// 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`.
#[attr_env_var_pattern("UV_INDEX_{name}_PASSWORD")]
pub fn index_password(name: &str) -> String {
format!("UV_INDEX_{name}_PASSWORD")
Expand Down Expand Up @@ -500,6 +514,7 @@ impl EnvVars {

/// 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.
Expand Down
29 changes: 22 additions & 7 deletions docs/configuration/environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ uv defines and respects the following environment variables:

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.
Expand Down Expand Up @@ -53,6 +54,7 @@ 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.
Expand Down Expand Up @@ -111,9 +113,11 @@ 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.
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`

Expand All @@ -123,11 +127,17 @@ URL as the default index when searching for packages.

### `UV_INDEX_{name}_PASSWORD`

Generates the environment variable key for the HTTP Basic authentication password.
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`

Generates the environment variable key for the HTTP Basic authentication username.
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_INSECURE_HOST`

Expand Down Expand Up @@ -232,6 +242,7 @@ 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.

Expand Down Expand Up @@ -266,8 +277,9 @@ 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
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`.
Expand Down Expand Up @@ -296,6 +308,7 @@ Specifies the directory for storing managed Python installations.

Managed Python installations are downloaded from the Astral
[`python-build-standalone`](https://github.com/astral-sh/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`.
Expand Down Expand Up @@ -324,6 +337,7 @@ Equivalent to the `--resolution` command-line argument. For example, if set to

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.
Expand Down Expand Up @@ -480,6 +494,7 @@ Adds directories to Python module search path (e.g., `PYTHONPATH=/path/to/module

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.
Expand Down
Loading