Warn when --upgrade is passed to tool run

crates/uv/src/lib.rs

@@ -738,7 +738,7 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
             };
 
             // Resolve the settings from the command-line arguments and workspace configuration.
-            let args = settings::ToolRunSettings::resolve(args, filesystem);
+            let args = settings::ToolRunSettings::resolve(args, filesystem, invocation_source);
             show_settings!(args);
 
             // Initialize the cache.

crates/uv/src/settings.rs

@@ -37,6 +37,7 @@ use uv_warnings::warn_user_once;
 use uv_workspace::pyproject::DependencyType;
 
 use crate::commands::pip::operations::Modifications;
+use crate::commands::ToolRunCommand;
 
 /// The resolved global settings to use for any invocation of the CLI.
 #[allow(clippy::struct_excessive_bools)]
@@ -276,7 +277,11 @@ pub(crate) struct ToolRunSettings {
 impl ToolRunSettings {
     /// Resolve the [`ToolRunSettings`] from the CLI and filesystem configuration.
     #[allow(clippy::needless_pass_by_value)]
-    pub(crate) fn resolve(args: ToolRunArgs, filesystem: Option<FilesystemOptions>) -> Self {
+    pub(crate) fn resolve(
+        args: ToolRunArgs,
+        filesystem: Option<FilesystemOptions>,
+        invocation_source: ToolRunCommand,
+    ) -> Self {
         let ToolRunArgs {
             command,
             from,
@@ -290,6 +295,11 @@ impl ToolRunSettings {
             python,
         } = args;
 
+        // If `--upgrade` was passed explicitly, warn.
+        if installer.upgrade || !installer.upgrade_package.is_empty() {
+            warn_user_once!("Tools cannot be upgraded via `{invocation_source}`; use `uv tool upgrade` to upgrade installed tools, or `{invocation_source} package@latest` to run the latest version of a tool");
+        }
+
         Self {
             command,
             from,

crates/uv/tests/tool_run.rs

@@ -373,25 +373,6 @@ fn tool_run_from_install() {
      + platformdirs==4.2.0
     "###);
 
-    // Verify that `--upgrade` resolves a fresh isolated environment (but reuses the cached
-    // environment resolved in the previous step).
-    uv_snapshot!(context.filters(), context.tool_run()
-        .arg("--upgrade")
-        .arg("black")
-        .arg("--version")
-        .env("UV_TOOL_DIR", tool_dir.as_os_str())
-        .env("XDG_BIN_HOME", bin_dir.as_os_str()), @r###"
-    success: true
-    exit_code: 0
-    ----- stdout -----
-    black, 24.3.0 (compiled: yes)
-    Python (CPython) 3.12.[X]
-
-    ----- stderr -----
-    warning: `uv tool run` is experimental and may change without warning
-    Resolved [N] packages in [TIME]
-    "###);
-
     // Verify that `tool run black` at a different version installs the new version.
     uv_snapshot!(context.filters(), context.tool_run()
         .arg("[email protected]")
@@ -903,6 +884,37 @@ fn warn_no_executables_found() {
     "###);
 }
 
+/// Warn when a user passes `--upgrade` to `uv tool run`.
+#[test]
+fn tool_run_upgrade_warn() {
+    let context = TestContext::new("3.12").with_filtered_counts();
+    let tool_dir = context.temp_dir.child("tools");
+    let bin_dir = context.temp_dir.child("bin");
+
+    uv_snapshot!(context.filters(), context.tool_run()
+        .arg("--upgrade")
+        .arg("pytest")
+        .arg("--version")
+        .env("UV_TOOL_DIR", tool_dir.as_os_str())
+        .env("XDG_BIN_HOME", bin_dir.as_os_str()), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    pytest 8.1.1
+
+    ----- stderr -----
+    warning: Tools cannot be upgraded via `uv tool run`; use `uv tool upgrade` to upgrade installed tools, or `uv tool run package@latest` to run the latest version of a tool
+    warning: `uv tool run` is experimental and may change without warning
+    Resolved [N] packages in [TIME]
+    Prepared [N] packages in [TIME]
+    Installed [N] packages in [TIME]
+     + iniconfig==2.0.0
+     + packaging==24.0
+     + pluggy==1.4.0
+     + pytest==8.1.1
+    "###);
+}
+
 /// If we fail to resolve the tool, we should include "tool" in the error message.
 #[test]
 fn tool_run_resolution_error() {