Publish: Hint at --skip-existing -> --check-url transition

crates/uv-cli/src/lib.rs

@@ -4882,8 +4882,11 @@ pub struct PublishArgs {
     /// file succeeds even without `--check-url`, while most other indexes error.
     ///
     /// The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
-    #[arg(long,env = EnvVars::UV_PUBLISH_CHECK_URL)]
+    #[arg(long, env = EnvVars::UV_PUBLISH_CHECK_URL)]
     pub check_url: Option<IndexUrl>,
+
+    #[arg(long, hide = true)]
+    pub skip_existing: bool,
 }
 
 /// See [PEP 517](https://peps.python.org/pep-0517/) and

crates/uv/src/lib.rs

@@ -7,7 +7,7 @@ use std::path::Path;
 use std::process::ExitCode;
 
 use anstream::eprintln;
-use anyhow::Result;
+use anyhow::{bail, Result};
 use clap::error::{ContextKind, ContextValue};
 use clap::{CommandFactory, Parser};
 use owo_colors::OwoColorize;
@@ -1130,6 +1130,16 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
                 warn_user_once!("`uv publish` is experimental and may change without warning");
             }
 
+            if args.skip_existing {
+                bail!(
+                    "`uv publish` does not support `--skip-existing` because there is not a \
+                    reliable way to identify when an upload fails due to an existing \
+                    distribution. Instead, use `--check-url` to provide the URL to the simple \
+                    API for your index. uv will check the index for existing distributions before \
+                    attempting uploads."
+                );
+            }
+
             // Resolve the settings from the command-line arguments and workspace configuration.
             let PublishSettings {
                 files,

crates/uv/tests/it/publish.rs

@@ -142,3 +142,23 @@ fn no_credentials() {
     "###
     );
 }
+
+/// Hint people that it's not `--skip-existing` but `--check-url`.
+#[test]
+fn skip_existing_redirect() {
+    let context = TestContext::new("3.12");
+
+    uv_snapshot!(context.filters(), context.publish()
+        .arg("--skip-existing")
+        .arg("--publish-url")
+        .arg("https://test.pypi.org/legacy/"), @r###"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    warning: `uv publish` is experimental and may change without warning
+    error: `uv publish` does not support `--skip-existing` because there is not a reliable way to identify when an upload fails due to an existing distribution. Instead, use `--check-url` to provide the URL to the simple API for your index. uv will check the index for existing distributions before attempting uploads.
+    "###
+    );
+}