diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 1b41050b2..7cd743bc6 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -4872,8 +4872,10 @@ pub enum PythonCommand { /// See `uv help python` to view supported request formats. Install(PythonInstallArgs), - /// Upgrade installed Python versions to the latest supported patch release (requires the - /// `--preview` flag). + /// Upgrade installed Python versions. + /// + /// Upgrades versions to the latest supported patch release. Requires the `python-upgrade` + /// preview feature. /// /// A target Python minor version to upgrade may be provided, e.g., `3.13`. Multiple versions /// may be provided to perform more than one upgrade. diff --git a/crates/uv/tests/it/help.rs b/crates/uv/tests/it/help.rs index d4f46b0cb..54c10e972 100644 --- a/crates/uv/tests/it/help.rs +++ b/crates/uv/tests/it/help.rs @@ -292,8 +292,7 @@ fn help_subcommand() { Commands: list List the available Python installations install Download and install Python versions - upgrade Upgrade installed Python versions to the latest supported patch release (requires - the `--preview` flag) + upgrade Upgrade installed Python versions find Search for a Python installation pin Pin to a specific Python version dir Show the uv Python installation directory @@ -731,8 +730,7 @@ fn help_flag_subcommand() { Commands: list List the available Python installations install Download and install Python versions - upgrade Upgrade installed Python versions to the latest supported patch release (requires - the `--preview` flag) + upgrade Upgrade installed Python versions find Search for a Python installation pin Pin to a specific Python version dir Show the uv Python installation directory diff --git a/docs/concepts/preview.md b/docs/concepts/preview.md new file mode 100644 index 000000000..c84eda380 --- /dev/null +++ b/docs/concepts/preview.md @@ -0,0 +1,74 @@ +# Preview features + +uv includes opt-in preview features to provide an opportunity for community feedback and increase +confidence that changes are a net-benefit before enabling them for everyone. + +## Enabling preview features + +To enable all preview features, use the `--preview` flag: + +```console +$ uv run --preview ... +``` + +Or, set the `UV_PREVIEW` environment variable: + +```console +$ UV_PREVIEW=1 uv run ... +``` + +To enable specific preview features, use the `--preview-features` flag: + +```console +$ uv run --preview-features foo ... +``` + +The `--preview-features` flag can be repeated to enable multiple features: + +```console +$ uv run --preview-features foo --preview-features bar ... +``` + +Or, features can be provided in a comma separated list: + +```console +$ uv run --preview-features foo,bar ... +``` + +The `UV_PREVIEW_FEATURES` environment variable can be used similarly, e.g.: + +```console +$ UV_PREVIEW_FEATURES=foo,bar uv run ... +``` + +For backwards compatibility, enabling preview features that do not exist will warn, but not error. + +## Using preview features + +Often, preview features can be used without changing any preview settings if the behavior change is +gated by some sort of user interaction, For example, while `pylock.toml` support is in preview, you +can use `uv pip install` with a `pylock.toml` file without additional configuration because +specifying the `pylock.toml` file indicates you want to use the feature. However, a warning will be +displayed that the feature is in preview. The preview feature can be enabled to silence the warning. + +Other preview features change behavior without changes to your use of uv. For example, when the +`python-upgrade` feature is enabled, the default behavior of `uv python install` changes to allow uv +to upgrade Python versions transparently. This feature requires enabling the preview flag for proper +usage. + +## Available preview features + +The following preview features are available: + +- `add-bounds`: Allows configuring the + [default bounds for `uv add`](../reference/settings.md#add-bounds) invocations. +- `json-output`: Allows `--output-format json` for various uv commands. +- `pylock`: Allows installing from `pylock.toml` files. +- `python-install-default`: Allows + [installing `python` and `python3` executables](./python-versions.md#installing-python-executables). +- `python-upgrade`: Allows + [transparent Python version upgrades](./python-versions.md#upgrading-python-versions). + +## Disabling preview features + +The `--no-preview` option can be used to disable preview features. diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index 0c16218d4..3632869db 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -180,9 +180,9 @@ $ uv python upgrade After an upgrade, uv will prefer the new version, but will retain the existing version as it may still be used by virtual environments. -If the Python version was installed with preview enabled, e.g., `uv python install 3.12 --preview`, -virtual environments using the Python version will be automatically upgraded to the new patch -version. +If the Python version was installed with the `python-upgrade` [preview feature](./preview.md) +enabled, e.g., `uv python install 3.12 --preview-features python-upgrade`, virtual environments +using the Python version will be automatically upgraded to the new patch version. !!! note diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9b27ea5cb..43f7a2aa7 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -2641,7 +2641,7 @@ uv python [OPTIONS]
uv python list

List the available Python installations

uv python install

Download and install Python versions

-
uv python upgrade

Upgrade installed Python versions to the latest supported patch release (requires the --preview flag)

+
uv python upgrade

Upgrade installed Python versions

uv python find

Search for a Python installation

uv python pin

Pin to a specific Python version

uv python dir

Show the uv Python installation directory

@@ -2843,7 +2843,9 @@ uv python install [OPTIONS] [TARGETS]... ### uv python upgrade -Upgrade installed Python versions to the latest supported patch release (requires the `--preview` flag). +Upgrade installed Python versions. + +Upgrades versions to the latest supported patch release. Requires the `python-upgrade` preview feature. A target Python minor version to upgrade may be provided, e.g., `3.13`. Multiple versions may be provided to perform more than one upgrade. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 69a299b5b..e5b214ecf 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -131,6 +131,7 @@ plugins: - concepts/build-backend.md - concepts/authentication.md - concepts/cache.md + - concepts/preview.md The pip interface: - pip/environments.md - pip/packages.md @@ -210,6 +211,7 @@ nav: - Build backend: concepts/build-backend.md - Authentication: concepts/authentication.md - Caching: concepts/cache.md + - Preview features: concepts/preview.md # Note: The `pip` section was moved to the `concepts/` section but the # top-level directory structure was retained to ease the transition. - The pip interface: