From e0a19be8252d2a1fa3a898cee1657a2ccbfb4581 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Thu, 30 Jan 2025 13:56:53 -0600
Subject: [PATCH] Touch-ups to the Python install guide (#11116)

---
 docs/concepts/python-versions.md |  2 ++
 docs/guides/install-python.md    | 40 +++++++++++++++++---------------
 2 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md
index 70da18fa8..c6f35519d 100644
--- a/docs/concepts/python-versions.md
+++ b/docs/concepts/python-versions.md
@@ -184,6 +184,8 @@ To exclude downloads and only show installed Python versions:
 $ uv python list --only-installed
 ```
 
+See the [`uv python list`](../reference/cli.md#uv-python-list) reference for more details.
+
 ## Finding a Python executable
 
 To find a Python executable, use the `uv python find` command:
diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md
index 2766b7295..f33a99a97 100644
--- a/docs/guides/install-python.md
+++ b/docs/guides/install-python.md
@@ -9,13 +9,8 @@ description:
 
 If Python is already installed on your system, uv will
 [detect and use](#using-existing-python-versions) it without configuration. However, uv can also
-install and manage Python versions for you.
-
-!!! tip
-
-    uv will [automatically fetch Python versions](#automatic-python-downloads) as needed — you don't need to install Python to get started.
-
-<!-- TODO(zanieb): I don't love this heading. -->
+install and manage Python versions. uv [automatically installs](#automatic-python-downloads) missing
+Python versions as needed — you don't need to install Python to get started.
 
 ## Getting started
 
@@ -25,12 +20,9 @@ To install the latest Python version:
 $ uv python install
 ```
 
-This will install a uv-managed Python version even if there is already a Python installation on your
-system. If you've previously installed Python with uv, a new version will not be installed.
-
 !!! note
 
-    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.
+    Python does not publish official distributable binaries. As such, uv uses distributions from the 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.
 
 Once Python is installed, it will be used by `uv` commands automatically.
 
@@ -67,6 +59,18 @@ $ uv python install pypy@3.10
 See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation
 for more details.
 
+## Reinstalling Python
+
+To reinstall uv-managed Python versions, use `--reinstall`, e.g.:
+
+```console
+$ uv python install --reinstall
+```
+
+This will reinstall all previously installed Python versions. Improvements are constantly being
+added to the Python distributions, so reinstalling may resolve bugs even if the Python version does
+not change.
+
 ## Viewing Python installations
 
 To view available and installed Python versions:
@@ -78,21 +82,19 @@ $ uv python list
 See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions)
 documentation for more details.
 
-<!--TODO(zanieb): The above should probably link to a CLI reference and that content should be moved out of that file -->
-
 ## Automatic Python downloads
 
-Note that Python does not need to be explicitly installed to use uv. By default, uv will
-automatically download Python versions when they are required. For example, the following would
-download Python 3.12 if it was not installed:
+Python does not need to be explicitly installed to use uv. By default, uv will automatically
+download Python versions when they are required. For example, the following would download Python
+3.12 if it was not installed:
 
 ```console
-$ uv run --python 3.12 python -c "print('hello world')"
+$ uvx python@3.12 -c "print('hello world')"
 ```
 
 Even if a specific Python version is not requested, uv will download the latest version on demand.
-For example, the following will create a new virtual environment and download a managed Python
-version if Python is not found:
+For example, if there are no Python versions on your system, the following will install Python
+before creating a new virtual environment:
 
 ```console
 $ uv venv