Require uv venv --clear before clearing an existing directory

Author: jtfmumm

Cargo.lock

@@ -334,6 +334,7 @@ impl SourceBuild {
                 uv_virtualenv::Prompt::None,
                 false,
                 false,
+                true,
                 false,
                 false,
                 false,

crates/uv-build-frontend/src/lib.rs

@@ -266,9 +266,6 @@ enum Resolver {
 /// These represent a subset of the `virtualenv` interface that uv supports by default.
 #[derive(Args)]
 pub struct VenvCompatArgs {
-    #[clap(long, hide = true)]
-    clear: bool,
-
     #[clap(long, hide = true)]
     no_seed: bool,
 
@@ -289,12 +286,6 @@ impl CompatArgs for VenvCompatArgs {
     /// behavior. If an argument is passed that does _not_ match uv's behavior, this method will
     /// return an error.
     fn validate(&self) -> Result<()> {
-        if self.clear {
-            warn_user!(
-                "virtualenv's `--clear` has no effect (uv always clears the virtual environment)"
-            );
-        }
-
         if self.no_seed {
             warn_user!(
                 "virtualenv's `--no-seed` has no effect (uv omits seed packages by default)"

crates/uv-cli/src/compat.rs

@@ -2562,16 +2562,23 @@ pub struct VenvArgs {
     #[arg(long, value_parser = clap::builder::BoolishValueParser::new(), env = EnvVars::UV_VENV_SEED)]
     pub seed: bool,
 
+    /// Remove any existing files or directories at the target path.
+    ///
+    /// By default, `uv venv` will exit with an error if the given path is non-empty. The
+    /// `--clear` option will instead clear a non-empty path before creating a new virtual
+    /// environment.
+    #[clap(long, short, conflicts_with = "allow_existing", value_parser = clap::builder::BoolishValueParser::new(), env = EnvVars::UV_VENV_CLEAR)]
+    pub clear: bool,
+
     /// Preserve any existing files or directories at the target path.
     ///
-    /// By default, `uv venv` will remove an existing virtual environment at the given path, and
-    /// exit with an error if the path is non-empty but _not_ a virtual environment. The
+    /// By default, `uv venv` will exit with an error if the given path is non-empty. The
     /// `--allow-existing` option will instead write to the given path, regardless of its contents,
     /// and without clearing it beforehand.
     ///
     /// WARNING: This option can lead to unexpected behavior if the existing virtual environment and
     /// the newly-created virtual environment are linked to different Python interpreters.
-    #[clap(long)]
+    #[clap(long, conflicts_with = "clear")]
     pub allow_existing: bool,
 
     /// The path to the virtual environment to create.

crates/uv-cli/src/lib.rs

@@ -292,6 +292,13 @@ impl EnvVars {
     /// Distributions can be read from a local directory by using the `file://` URL scheme.
     pub const UV_PYPY_INSTALL_MIRROR: &'static str = "UV_PYPY_INSTALL_MIRROR";
 
+    /// Remove any existing files or directories at the target path.
+    ///
+    /// By default, `uv venv` will exit with an error if the given path is non-empty. The
+    /// `--clear` option will instead clear a non-empty path before creating a new virtual
+    /// environment.
+    pub const UV_VENV_CLEAR: &'static str = "UV_VENV_CLEAR";
+
     /// Install seed packages (one or more of: `pip`, `setuptools`, and `wheel`) into the virtual environment
     /// created by `uv venv`.
     ///

crates/uv-static/src/env_vars.rs

@@ -286,6 +286,7 @@ impl InstalledTools {
             uv_virtualenv::Prompt::None,
             false,
             false,
+            true,
             false,
             false,
             false,

crates/uv-tool/src/lib.rs

@@ -21,14 +21,17 @@ workspace = true
 
 [dependencies]
 uv-configuration = { workspace = true }
+uv-console = { workspace = true }
 uv-fs = { workspace = true }
 uv-pypi-types = { workspace = true }
 uv-python = { workspace = true }
 uv-shell = { workspace = true }
 uv-version = { workspace = true }
 
+console = { workspace = true }
 fs-err = { workspace = true }
 itertools = { workspace = true }
+owo-colors = { workspace = true }
 pathdiff = { workspace = true }
 thiserror = { workspace = true }
 tracing = { workspace = true }

crates/uv-virtualenv/Cargo.toml

@@ -51,6 +51,7 @@ pub fn create_venv(
     prompt: Prompt,
     system_site_packages: bool,
     allow_existing: bool,
+    clear: bool,
     relocatable: bool,
     seed: bool,
     upgradeable: bool,
@@ -63,6 +64,7 @@ pub fn create_venv(
         prompt,
         system_site_packages,
         allow_existing,
+        clear,
         relocatable,
         seed,
         upgradeable,

crates/uv-virtualenv/src/lib.rs

@@ -5,9 +5,11 @@ use std::io;
 use std::io::{BufWriter, Write};
 use std::path::Path;
 
+use console::Term;
 use fs_err as fs;
 use fs_err::File;
 use itertools::Itertools;
+use owo_colors::OwoColorize;
 use tracing::debug;
 
 use uv_configuration::PreviewMode;
@@ -53,6 +55,7 @@ pub(crate) fn create(
     prompt: Prompt,
     system_site_packages: bool,
     allow_existing: bool,
+    clear: bool,
     relocatable: bool,
     seed: bool,
     upgradeable: bool,
@@ -83,10 +86,17 @@ pub(crate) fn create(
                     format!("File exists at `{}`", location.user_display()),
                 )));
             } else if metadata.is_dir() {
+                let confirmation_required = !clear && !allow_existing;
+                let confirmed_clear = confirmation_required && confirm_clear(location)?;
+
                 if allow_existing {
-                    debug!("Allowing existing directory");
-                } else if uv_fs::is_virtualenv_base(location) {
-                    debug!("Removing existing directory");
+                    debug!("Allowing existing directory due to `--allow-existing`");
+                } else if clear || confirmed_clear {
+                    if clear {
+                        debug!("Removing existing directory due to `--clear`");
+                    } else {
+                        debug!("Removing existing directory");
+                    }
 
                     // On Windows, if the current executable is in the directory, guard against
                     // self-deletion.
@@ -110,8 +120,12 @@ pub(crate) fn create(
                     return Err(Error::Io(io::Error::new(
                         io::ErrorKind::AlreadyExists,
                         format!(
-                            "The directory `{}` exists, but it's not a virtual environment",
-                            location.user_display()
+                            "The directory `{}` exists. \n\n{}{} Use `{}` to remove the directory first or `{}` to write to the directory without clearing",
+                            location.user_display(),
+                            "hint".bold().cyan(),
+                            ":".bold(),
+                            "--clear".green(),
+                            "--allow-existing".green(),
                         ),
                     )));
                 }
@@ -464,6 +478,19 @@ pub(crate) fn create(
     })
 }
 
+fn confirm_clear(location: &Path) -> Result<bool, io::Error> {
+    let term = Term::stderr();
+    if term.is_term() {
+        let prompt = format!(
+            "The directory `{}` exists. Did you mean to clear its contents (`--clear`)?",
+            location.user_display(),
+        );
+        uv_console::confirm(&prompt, &term, true)
+    } else {
+        Ok(false)
+    }
+}
+
 #[derive(Debug, Copy, Clone)]
 enum WindowsExecutable {
     /// The `python.exe` executable (or `venvlauncher.exe` launcher shim).

crates/uv-virtualenv/src/virtualenv.rs

@@ -97,6 +97,7 @@ impl CachedEnvironment {
             false,
             false,
             true,
+            true,
             false,
             false,
             preview,