From 8908e26de795517df4f59312becdebd226fa658f Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Thu, 19 Dec 2024 16:07:46 -0600
Subject: [PATCH] Add `uv python install --preview` to the documentation
 (#10010)

---
 docs/concepts/python-versions.md | 39 ++++++++++++++++++++++++++++++++
 docs/guides/install-python.md    | 17 ++++----------
 2 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md
index a85eb6ca73d3..85dbb25c6b43 100644
--- a/docs/concepts/python-versions.md
+++ b/docs/concepts/python-versions.md
@@ -110,6 +110,45 @@ latest version. If a `.python-version` file is present, uv will install the Pyth
 the file. A project that requires multiple Python versions may define a `.python-versions` file. If
 present, uv will install all of the Python versions listed in the file.
 
+### Installing Python executables
+
+!!! important
+
+    Support for installing Python executables is in _preview_, this means the behavior is experimental
+    and subject to change.
+
+To install Python executables into your `PATH`, provide the `--preview` option:
+
+```console
+$ uv python install 3.12 --preview
+```
+
+This will install a Python executable for the requested version into `~/.local/bin`, e.g., as
+`python3.12`.
+
+!!! tip
+
+    If `~/.local/bin` is not in your `PATH`, you can add it with `uv tool update-shell`.
+
+To install `python` and `python3` executables, include the `--default` option:
+
+```console
+$ uv python install 3.12 --default --preview
+```
+
+When installing Python executables, uv will only overwrite an existing executable if it is managed
+by uv — e.g., if `~/.local/bin/python3.12` exists already uv will not overwrite it without the
+`--force` flag.
+
+uv will update executables that it manages. However, it will prefer the latest patch version of each
+Python minor version by default. For example:
+
+```console
+$ uv python install 3.12.7 --preview  # Adds `python3.12` to `~/.local/bin`
+$ uv python install 3.12.6 --preview  # Does not update `python3.12`
+$ uv python install 3.12.8 --preview  # Updates `python3.12` to point to 3.12.8
+```
+
 ## Project Python versions
 
 uv will respect Python requirements defined in `requires-python` in the `pyproject.toml` file during
diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md
index 2711f34eb0b6..9cefc830ccb4 100644
--- a/docs/guides/install-python.md
+++ b/docs/guides/install-python.md
@@ -25,24 +25,15 @@ system. If you've previously installed Python with uv, a new version will not be
 
     Python does not publish official distributable binaries. As such, uv uses distributions from Astral [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone) project. See the [Python distributions](../concepts/python-versions.md#managed-python-distributions) documentation for more details.
 
-<!-- TODO(zanieb): Restore when Python shim management is added
-Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed.
-
-Once Python is installed, it can be invoked via `python`:
-
-```console
-$ python --version
-```
-
-To prevent uv from managing Python system-wide, provide the `--no-shim` option during installation.
--->
-
 Once Python is installed, it will be used by `uv` commands automatically.
 
 !!! important
 
     When Python is installed by uv, it will not be available globally (i.e. via the `python` command).
-    Support for this feature is planned for a future release. In the meantime, use
+    Support for this feature is in _preview_. See [Installing Python executables](../concepts/python-versions.md#installing-python-executables)
+    for details.
+
+    You can still use
     [`uv run`](../guides/scripts.md#using-different-python-versions) or
     [create and activate a virtual environment](../pip/environments.md) to use `python` directly.