Add note about available versions (#11331)

ref #11243 (comment)

Author: zanieb

crates/uv-cli/src/lib.rs

@@ -4332,10 +4332,10 @@ pub enum PythonCommand {
 
     /// Download and install Python versions.
     ///
-    /// Multiple Python versions may be requested.
-    ///
     /// Supports CPython and PyPy. CPython distributions are downloaded from the Astral
-    /// `python-build-standalone` project. PyPy distributions are downloaded from `python.org`.
+    /// `python-build-standalone` project. PyPy distributions are downloaded from `python.org`. The
+    /// available Python versions are bundled with each uv release. To install new Python versions,
+    /// you may need upgrade uv.
     ///
     /// Python versions are installed into the uv Python directory, which can be retrieved with `uv
     /// python dir`.
@@ -4344,6 +4344,8 @@ pub enum PythonCommand {
     /// in uv commands or in active virtual environments. There is experimental support for adding
     /// Python executables to the `PATH` — use the `--preview` flag to enable this behavior.
     ///
+    /// Multiple Python versions may be requested.
+    ///
     /// See `uv help python` to view supported request formats.
     Install(PythonInstallArgs),
 

crates/uv/tests/it/help.rs

@@ -458,10 +458,10 @@ fn help_subsubcommand() {
     ----- stdout -----
     Download and install Python versions.
 
-    Multiple Python versions may be requested.
-
     Supports CPython and PyPy. CPython distributions are downloaded from the Astral
-    `python-build-standalone` project. PyPy distributions are downloaded from `python.org`.
+    `python-build-standalone` project. PyPy distributions are downloaded from `python.org`. The
+    available Python versions are bundled with each uv release. To install new Python versions, you may
+    need upgrade uv.
 
     Python versions are installed into the uv Python directory, which can be retrieved with `uv python
     dir`.
@@ -470,6 +470,8 @@ fn help_subsubcommand() {
     commands or in active virtual environments. There is experimental support for adding Python
     executables to the `PATH` — use the `--preview` flag to enable this behavior.
 
+    Multiple Python versions may be requested.
+
     See `uv help python` to view supported request formats.
 
     Usage: uv python install [OPTIONS] [TARGETS]...

docs/concepts/python-versions.md

@@ -110,6 +110,11 @@ 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.
 
+!!! important
+
+    The available Python versions are frozen for each uv release. To install new Python versions,
+    you may need upgrade uv.
+
 ### Installing Python executables
 
 !!! important

docs/reference/cli.md

@@ -4742,14 +4742,14 @@ uv python list [OPTIONS]
 
 Download and install Python versions.
 
-Multiple Python versions may be requested.
-
-Supports CPython and PyPy. CPython distributions are downloaded from the Astral `python-build-standalone` project. PyPy distributions are downloaded from `python.org`.
+Supports CPython and PyPy. CPython distributions are downloaded from the Astral `python-build-standalone` project. PyPy distributions are downloaded from `python.org`. The available Python versions are bundled with each uv release. To install new Python versions, you may need upgrade uv.
 
 Python versions are installed into the uv Python directory, which can be retrieved with `uv python dir`.
 
 A `python` executable is not made globally available, managed Python versions are only used in uv commands or in active virtual environments. There is experimental support for adding Python executables to the `PATH` — use the `--preview` flag to enable this behavior.
 
+Multiple Python versions may be requested.
+
 See `uv help python` to view supported request formats.
 
 <h3 class="cli-reference">Usage</h3>