Require uv venv --clear before removing an existing directory (#14309)

By default, `uv venv <venv-name>` currently removes the `<venv-name`>
directory if it exists. This can be surprising behavior: not everyone
expects an existing environment to be overwritten. This PR updates the
default to fail if a non-empty `<venv-name>` directory already exists
and neither `--allow-existing` nor the new `-c/--clear` option is
provided (if a TTY is detected, it prompts first). If it's not a TTY,
then uv will only warn and not fail for now — we'll make this an error
in the future. I've also added a corresponding `UV_VENV_CLEAR` env var.

I've chosen to use `--clear` instead of `--force` for this option
because it is used by the `venv` module and `virtualenv` and will be
familiar to users. I also think its meaning is clearer in this context
than `--force` (which could plausibly mean force overwrite just the
virtual environment files, which is what our current `--allow-existing`
option does).

Closes #1472.

---------

Co-authored-by: Zanie Blue <[email protected]>

Author: jtfmumm

.github/workflows/ci.yml

@@ -1042,7 +1042,7 @@ jobs:
 
       - name: "Create a virtual environment (uv)"
         run: |
-          ./uv venv -p 3.13t --managed-python
+          ./uv venv -c -p 3.13t --managed-python
 
       - name: "Check version (uv)"
         run: |
@@ -1087,7 +1087,7 @@ jobs:
 
       - name: "Create a virtual environment (uv)"
         run: |
-          ./uv venv -p 3.13 --managed-python
+          ./uv venv -c -p 3.13 --managed-python
 
       - name: "Check version (uv)"
         run: |
@@ -1132,7 +1132,7 @@ jobs:
 
       - name: "Create a virtual environment (uv)"
         run: |
-          ./uv venv -p 3.13 --managed-python
+          ./uv venv -c -p 3.13 --managed-python
 
       - name: "Check version (uv)"
         run: |
@@ -1758,14 +1758,14 @@ jobs:
           ./uv run --no-project python -c "from built_by_uv import greet; print(greet())"
 
           # Test both `build_wheel` and `build_sdist` through uv
-          ./uv venv -v
+          ./uv venv -c -v
           ./uv build -v --force-pep517 scripts/packages/built-by-uv --find-links crates/uv-build/dist --offline
           ./uv pip install -v scripts/packages/built-by-uv/dist/*.tar.gz --find-links crates/uv-build/dist --offline --no-deps
           ./uv run --no-project python -c "from built_by_uv import greet; print(greet())"
 
           # Test both `build_wheel` and `build_sdist` through the official `build`
           rm -rf scripts/packages/built-by-uv/dist/
-          ./uv venv -v
+          ./uv venv -c -v
           ./uv pip install build
           # Add the uv binary to PATH for `build` to find
           PATH="$(pwd):$PATH" UV_OFFLINE=1 UV_FIND_LINKS=crates/uv-build/dist ./uv run --no-project python -m build -v --installer uv scripts/packages/built-by-uv

Cargo.lock

@@ -331,7 +331,7 @@ impl SourceBuild {
                 interpreter.clone(),
                 uv_virtualenv::Prompt::None,
                 false,
-                false,
+                uv_virtualenv::OnExisting::Remove,
                 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

@@ -2615,16 +2615,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, overrides_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, overrides_with = "clear")]
     pub allow_existing: bool,
 
     /// The path to the virtual environment to create.

crates/uv-cli/src/lib.rs

@@ -6,6 +6,25 @@ use std::{cmp::Ordering, iter};
 /// This is a slimmed-down version of `dialoguer::Confirm`, with the post-confirmation report
 /// enabled.
 pub fn confirm(message: &str, term: &Term, default: bool) -> std::io::Result<bool> {
+    confirm_inner(message, None, term, default)
+}
+
+/// Prompt the user for confirmation in the given [`Term`], with a hint.
+pub fn confirm_with_hint(
+    message: &str,
+    hint: &str,
+    term: &Term,
+    default: bool,
+) -> std::io::Result<bool> {
+    confirm_inner(message, Some(hint), term, default)
+}
+
+fn confirm_inner(
+    message: &str,
+    hint: Option<&str>,
+    term: &Term,
+    default: bool,
+) -> std::io::Result<bool> {
     let prompt = format!(
         "{} {} {} {} {}",
         style("?".to_string()).for_stderr().yellow(),
@@ -18,6 +37,13 @@ pub fn confirm(message: &str, term: &Term, default: bool) -> std::io::Result<boo
     );
 
     term.write_str(&prompt)?;
+    if let Some(hint) = hint {
+        term.write_str(&format!(
+            "\n\n{}{} {hint}",
+            style("hint").for_stderr().bold().cyan(),
+            style(":").for_stderr().bold()
+        ))?;
+    }
     term.hide_cursor()?;
     term.flush()?;
 
@@ -56,7 +82,11 @@ pub fn confirm(message: &str, term: &Term, default: bool) -> std::io::Result<boo
             .cyan(),
     );
 
-    term.clear_line()?;
+    if hint.is_some() {
+        term.clear_last_lines(2)?;
+    } else {
+        term.clear_line()?;
+    }
     term.write_line(&report)?;
     term.show_cursor()?;
     term.flush()?;

crates/uv-console/src/lib.rs

@@ -292,6 +292,10 @@ 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";
 
+    /// Equivalent to the `--clear` command-line argument. If set, uv will remove any
+    /// existing files or directories at the target path.
+    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

@@ -285,7 +285,7 @@ impl InstalledTools {
             interpreter,
             uv_virtualenv::Prompt::None,
             false,
-            false,
+            uv_virtualenv::OnExisting::Remove,
             false,
             false,
             false,

crates/uv-tool/src/lib.rs

@@ -21,14 +21,18 @@ 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 }
+uv-warnings = { 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

@@ -6,6 +6,8 @@ use thiserror::Error;
 use uv_configuration::PreviewMode;
 use uv_python::{Interpreter, PythonEnvironment};
 
+pub use virtualenv::OnExisting;
+
 mod virtualenv;
 
 #[derive(Debug, Error)]
@@ -50,7 +52,7 @@ pub fn create_venv(
     interpreter: Interpreter,
     prompt: Prompt,
     system_site_packages: bool,
-    allow_existing: bool,
+    on_existing: OnExisting,
     relocatable: bool,
     seed: bool,
     upgradeable: bool,
@@ -62,7 +64,7 @@ pub fn create_venv(
         &interpreter,
         prompt,
         system_site_packages,
-        allow_existing,
+        on_existing,
         relocatable,
         seed,
         upgradeable,