Update documentation for preview flags (#14902)

Follows #14823

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
+    /// Upgrade installed Python versions.
-    /// `--preview` flag).
+    ///
+    /// 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.

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
+      upgrade       Upgrade installed Python versions
-                    the `--preview` flag)
       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
+      upgrade       Upgrade installed Python versions
-                    the `--preview` flag)
       find          Search for a Python installation
       pin           Pin to a specific Python version
       dir           Show the uv Python installation directory

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.

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`,
+If the Python version was installed with the `python-upgrade` [preview feature](./preview.md)
-virtual environments using the Python version will be automatically upgraded to the new patch
+enabled, e.g., `uv python install 3.12 --preview-features python-upgrade`, virtual environments
-version.
+using the Python version will be automatically upgraded to the new patch version.
 
 !!! note
 

docs/reference/cli.md

@@ -2641,7 +2641,7 @@ uv python [OPTIONS] <COMMAND>
 
 <dl class="cli-reference"><dt><a href="#uv-python-list"><code>uv python list</code></a></dt><dd><p>List the available Python installations</p></dd>
 <dt><a href="#uv-python-install"><code>uv python install</code></a></dt><dd><p>Download and install Python versions</p></dd>
-<dt><a href="#uv-python-upgrade"><code>uv python upgrade</code></a></dt><dd><p>Upgrade installed Python versions to the latest supported patch release (requires the <code>--preview</code> flag)</p></dd>
+<dt><a href="#uv-python-upgrade"><code>uv python upgrade</code></a></dt><dd><p>Upgrade installed Python versions</p></dd>
 <dt><a href="#uv-python-find"><code>uv python find</code></a></dt><dd><p>Search for a Python installation</p></dd>
 <dt><a href="#uv-python-pin"><code>uv python pin</code></a></dt><dd><p>Pin to a specific Python version</p></dd>
 <dt><a href="#uv-python-dir"><code>uv python dir</code></a></dt><dd><p>Show the uv Python installation directory</p></dd>
@@ -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.
 

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: