From fc3dacf9a08c967f74415ad6a518bac1abeed81b Mon Sep 17 00:00:00 2001
From: Jo <10510431+j178@users.noreply.github.com>
Date: Wed, 16 Apr 2025 23:51:47 +0800
Subject: [PATCH] Improve docs for `uv python list --only-downloads` and
 `--only-installed` (#12916)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Only show Python downloads, exclude installed distributions." might be
misunderstood as excluding installed distributions from `uv python list
--only-downloads`, implying that versions already installed won’t be
shown.
---
 crates/uv-cli/src/lib.rs | 8 ++++----
 docs/reference/cli.md    | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs
index f3ac89b99..9b3e51a52 100644
--- a/crates/uv-cli/src/lib.rs
+++ b/crates/uv-cli/src/lib.rs
@@ -4643,15 +4643,15 @@ pub struct PythonListArgs {
     #[arg(long, alias = "all_architectures")]
     pub all_arches: bool,
 
-    /// Only show installed Python versions, exclude available downloads.
+    /// Only show installed Python versions.
     ///
-    /// By default, available downloads for the current platform are shown.
+    /// By default, installed distributions and available downloads for the current platform are shown.
     #[arg(long, conflicts_with("only_downloads"))]
     pub only_installed: bool,
 
-    /// Only show Python downloads, exclude installed distributions.
+    /// Only show available Python downloads.
     ///
-    /// By default, available downloads for the current platform are shown.
+    /// By default, installed distributions and available downloads for the current platform are shown.
     #[arg(long, conflicts_with("only_installed"))]
     pub only_downloads: bool,
 
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 7c18deb89..abd779e00 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -4766,13 +4766,13 @@ uv python list [OPTIONS] [REQUEST]
 <p>When disabled, uv will only use locally cached data and locally available files.</p>
 
 <p>May also be set with the <code>UV_OFFLINE</code> environment variable.</p>
-</dd><dt id="uv-python-list--only-downloads"><a href="#uv-python-list--only-downloads"><code>--only-downloads</code></a></dt><dd><p>Only show Python downloads, exclude installed distributions.</p>
+</dd><dt id="uv-python-list--only-downloads"><a href="#uv-python-list--only-downloads"><code>--only-downloads</code></a></dt><dd><p>Only show available Python downloads.</p>
 
-<p>By default, available downloads for the current platform are shown.</p>
+<p>By default, installed distributions and available downloads for the current platform are shown.</p>
 
-</dd><dt id="uv-python-list--only-installed"><a href="#uv-python-list--only-installed"><code>--only-installed</code></a></dt><dd><p>Only show installed Python versions, exclude available downloads.</p>
+</dd><dt id="uv-python-list--only-installed"><a href="#uv-python-list--only-installed"><code>--only-installed</code></a></dt><dd><p>Only show installed Python versions.</p>
 
-<p>By default, available downloads for the current platform are shown.</p>
+<p>By default, installed distributions and available downloads for the current platform are shown.</p>
 
 </dd><dt id="uv-python-list--output-format"><a href="#uv-python-list--output-format"><code>--output-format</code></a> <i>output-format</i></dt><dd><p>Select the output format</p>