Allow --force to overwrite existing virtualenv (#2548)

## Summary

Closes #2529.

## Test Plan

- `mkdir .venv`
- `touch .venv/foo`
- `cargo run venv` (ensure failure)
- `cargo run venv --force` (ensure success)
- `cargo run venv --force` (ensure success again)

crates/uv-build/src/lib.rs

@@ -414,6 +414,7 @@ impl SourceBuild {
                 interpreter.clone(),
                 uv_virtualenv::Prompt::None,
                 false,
+                false,
             )?,
             BuildIsolation::Shared(venv) => venv.clone(),
         };

crates/uv-fs/src/lib.rs

@@ -86,19 +86,26 @@ pub fn replace_symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io:
     )
 }
 
-/// Create a symlink from `src` to `dst`, replacing any existing symlink.
+/// Create a symlink from `src` to `dst`, replacing any existing symlink if necessary.
 #[cfg(unix)]
 pub fn replace_symlink(src: impl AsRef<Path>, dst: impl AsRef<Path>) -> std::io::Result<()> {
-    // Create a symlink to the directory store.
-    let temp_dir =
-        tempfile::tempdir_in(dst.as_ref().parent().expect("Cache entry to have parent"))?;
-    let temp_file = temp_dir.path().join("link");
-    std::os::unix::fs::symlink(src, &temp_file)?;
+    // Attempt to create the symlink directly.
+    match std::os::unix::fs::symlink(src.as_ref(), dst.as_ref()) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => {
+            // Create a symlink to the directory store, using a temporary file to ensure atomicity.
+            let temp_dir =
+                tempfile::tempdir_in(dst.as_ref().parent().expect("Cache entry to have parent"))?;
+            let temp_file = temp_dir.path().join("link");
+            std::os::unix::fs::symlink(src, &temp_file)?;
 
-    // Move the symlink into the wheel cache.
-    fs_err::rename(&temp_file, dst.as_ref())?;
+            // Move the symlink into the wheel cache.
+            fs_err::rename(&temp_file, dst.as_ref())?;
 
-    Ok(())
+            Ok(())
+        }
+        Err(err) => Err(err),
+    }
 }
 
 /// Write `data` to `path` atomically using a temporary file and atomic rename.

crates/uv-virtualenv/src/bare.rs

@@ -47,6 +47,7 @@ pub fn create_bare_venv(
     interpreter: &Interpreter,
     prompt: Prompt,
     system_site_packages: bool,
+    force: bool,
 ) -> Result<Virtualenv, Error> {
     // Determine the base Python executable; that is, the Python executable that should be
     // considered the "base" for the virtual environment. This is typically the Python executable
@@ -88,7 +89,9 @@ pub fn create_bare_venv(
                     format!("File exists at `{}`", location.user_display()),
                 )));
             } else if metadata.is_dir() {
-                if location.join("pyvenv.cfg").is_file() {
+                if force {
+                    info!("Overwriting existing directory");
+                } else if location.join("pyvenv.cfg").is_file() {
                     info!("Removing existing directory");
                     fs::remove_dir_all(location)?;
                     fs::create_dir_all(location)?;
@@ -147,19 +150,17 @@ pub fn create_bare_venv(
     })?;
 
     // Different names for the python interpreter
-    fs::create_dir(&scripts)?;
+    fs::create_dir_all(&scripts)?;
     let executable = scripts.join(format!("python{EXE_SUFFIX}"));
 
     #[cfg(unix)]
     {
-        use fs_err::os::unix::fs::symlink;
-
-        symlink(&base_python, &executable)?;
-        symlink(
+        uv_fs::replace_symlink(&base_python, &executable)?;
+        uv_fs::replace_symlink(
             "python",
             scripts.join(format!("python{}", interpreter.python_major())),
         )?;
-        symlink(
+        uv_fs::replace_symlink(
             "python",
             scripts.join(format!(
                 "python{}.{}",

crates/uv-virtualenv/src/lib.rs

@@ -51,9 +51,10 @@ pub fn create_venv(
     interpreter: Interpreter,
     prompt: Prompt,
     system_site_packages: bool,
+    force: bool,
 ) -> Result<PythonEnvironment, Error> {
     // Create the virtualenv at the given location.
-    let virtualenv = create_bare_venv(location, &interpreter, prompt, system_site_packages)?;
+    let virtualenv = create_bare_venv(location, &interpreter, prompt, system_site_packages, force)?;
 
     // Create the corresponding `PythonEnvironment`.
     let interpreter = interpreter.with_virtualenv(virtualenv);

crates/uv-virtualenv/src/main.rs

@@ -46,6 +46,7 @@ fn run() -> Result<(), uv_virtualenv::Error> {
         &interpreter,
         Prompt::from_args(cli.prompt),
         cli.system_site_packages,
+        false,
     )?;
     Ok(())
 }

crates/uv/src/cli.rs

@@ -1679,6 +1679,15 @@ pub(crate) struct VenvArgs {
     #[arg(long)]
     pub(crate) seed: bool,
 
+    /// Overwrite the directory at the specified path when creating the virtual environment.
+    ///
+    /// 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 `--force`
+    /// option will instead write to the given path, regardless of its contents, and without
+    /// clearing it beforehand.
+    #[clap(long)]
+    pub(crate) force: bool,
+
     /// The path to the virtual environment to create.
     #[arg(default_value = ".venv")]
     pub(crate) name: PathBuf,

crates/uv/src/commands/run.rs

@@ -268,6 +268,7 @@ async fn environment_for_run(
         python_env.into_interpreter(),
         uv_virtualenv::Prompt::None,
         false,
+        false,
     )?;
 
     // Determine the tags, markers, and interpreter to use for resolution.

crates/uv/src/commands/venv.rs

@@ -29,7 +29,11 @@ use crate::printer::Printer;
 use crate::shell::Shell;
 
 /// Create a virtual environment.
-#[allow(clippy::unnecessary_wraps, clippy::too_many_arguments)]
+#[allow(
+    clippy::unnecessary_wraps,
+    clippy::too_many_arguments,
+    clippy::fn_params_excessive_bools
+)]
 pub(crate) async fn venv(
     path: &Path,
     python_request: Option<&str>,
@@ -41,6 +45,7 @@ pub(crate) async fn venv(
     system_site_packages: bool,
     connectivity: Connectivity,
     seed: bool,
+    force: bool,
     exclude_newer: Option<ExcludeNewer>,
     native_tls: bool,
     cache: &Cache,
@@ -57,6 +62,7 @@ pub(crate) async fn venv(
         system_site_packages,
         connectivity,
         seed,
+        force,
         exclude_newer,
         native_tls,
         cache,
@@ -92,7 +98,7 @@ enum VenvError {
 }
 
 /// Create a virtual environment.
-#[allow(clippy::too_many_arguments)]
+#[allow(clippy::too_many_arguments, clippy::fn_params_excessive_bools)]
 async fn venv_impl(
     path: &Path,
     python_request: Option<&str>,
@@ -104,6 +110,7 @@ async fn venv_impl(
     system_site_packages: bool,
     connectivity: Connectivity,
     seed: bool,
+    force: bool,
     exclude_newer: Option<ExcludeNewer>,
     native_tls: bool,
     cache: &Cache,
@@ -140,7 +147,7 @@ async fn venv_impl(
     .into_diagnostic()?;
 
     // Create the virtual environment.
-    let venv = uv_virtualenv::create_venv(path, interpreter, prompt, system_site_packages)
+    let venv = uv_virtualenv::create_venv(path, interpreter, prompt, system_site_packages, force)
         .map_err(VenvError::Creation)?;
 
     // Install seed packages.

crates/uv/src/main.rs

@@ -478,6 +478,7 @@ async fn run() -> Result<ExitStatus> {
                 args.system_site_packages,
                 args.shared.connectivity,
                 args.seed,
+                args.force,
                 args.shared.exclude_newer,
                 globals.native_tls,
                 &cache,

crates/uv/src/settings.rs

@@ -736,6 +736,7 @@ impl PipCheckSettings {
 pub(crate) struct VenvSettings {
     // CLI-only settings.
     pub(crate) seed: bool,
+    pub(crate) force: bool,
     pub(crate) name: PathBuf,
     pub(crate) prompt: Option<String>,
     pub(crate) system_site_packages: bool,
@@ -752,6 +753,7 @@ impl VenvSettings {
             system,
             no_system,
             seed,
+            force,
             name,
             prompt,
             system_site_packages,
@@ -770,6 +772,7 @@ impl VenvSettings {
         Self {
             // CLI-only settings.
             seed,
+            force,
             name,
             prompt,
             system_site_packages,