Add --force flag for uv cache clean

Author: zanieb

crates/uv-cache/src/lib.rs

@@ -209,6 +209,33 @@ impl Cache {
         })
     }
 
+    /// Acquire a lock that allows removing entries from the cache, if available.
+    ///
+    /// If the lock is not immediately available, returns [`Err`] with self.
+    pub fn with_exclusive_lock_no_wait(self) -> Result<Self, Self> {
+        let Self {
+            root,
+            refresh,
+            temp_dir,
+            lock_file,
+        } = self;
+
+        match LockedFile::acquire_no_wait(root.join(".lock"), root.simplified_display()) {
+            Some(lock_file) => Ok(Self {
+                root,
+                refresh,
+                temp_dir,
+                lock_file: Some(Arc::new(lock_file)),
+            }),
+            None => Err(Self {
+                root,
+                refresh,
+                temp_dir,
+                lock_file,
+            }),
+        }
+    }
+
     /// Return the root of the cache.
     pub fn root(&self) -> &Path {
         &self.root

crates/uv-cli/src/lib.rs

@@ -775,6 +775,13 @@ pub enum CacheCommand {
 pub struct CleanArgs {
     /// The packages to remove from the cache.
     pub package: Vec<PackageName>,
+
+    /// Force removal of the cache, ignoring in-use checks.
+    ///
+    /// By default, `uv cache clean` will block until no process is reading the cache. When
+    /// `--force` is used, `uv cache clean` will proceed without taking a lock.
+    #[arg(long)]
+    pub force: bool,
 }
 
 #[derive(Args, Debug)]

crates/uv-fs/src/lib.rs

@@ -693,6 +693,28 @@ impl LockedFile {
         }
     }
 
+    /// Inner implementation for [`LockedFile::acquire_no_wait`].
+    fn lock_file_no_wait(file: fs_err::File, resource: &str) -> Option<Self> {
+        trace!(
+            "Checking lock for `{resource}` at `{}`",
+            file.path().user_display()
+        );
+        match file.file().try_lock_exclusive() {
+            Ok(()) => {
+                debug!("Acquired lock for `{resource}`");
+                Some(Self(file))
+            }
+            Err(err) => {
+                // Log error code and enum kind to help debugging more exotic failures.
+                if err.kind() != std::io::ErrorKind::WouldBlock {
+                    debug!("Try lock error: {err:?}");
+                }
+                debug!("Lock is busy for `{resource}`");
+                None
+            }
+        }
+    }
+
     /// Inner implementation for [`LockedFile::acquire_shared_blocking`] and
     /// [`LockedFile::acquire_blocking`].
     fn lock_file_shared_blocking(
@@ -782,6 +804,17 @@ impl LockedFile {
             .await?
     }
 
+    /// Acquire a cross-process lock for a resource using a file at the provided path
+    ///
+    /// Unlike [`LockedFile::acquire`] this function will not wait for the lock to become available.
+    ///
+    /// If the lock is not immediately available, [`None`] is returned.
+    pub fn acquire_no_wait(path: impl AsRef<Path>, resource: impl Display) -> Option<Self> {
+        let file = Self::create(path).ok()?;
+        let resource = resource.to_string();
+        Self::lock_file_no_wait(file, &resource)
+    }
+
     #[cfg(unix)]
     fn create(path: impl AsRef<Path>) -> Result<fs_err::File, std::io::Error> {
         use std::os::unix::fs::PermissionsExt;

crates/uv/src/commands/cache_clean.rs

@@ -2,6 +2,7 @@ use std::fmt::Write;
 
 use anyhow::{Context, Result};
 use owo_colors::OwoColorize;
+use tracing::debug;
 
 use uv_cache::{Cache, Removal};
 use uv_fs::Simplified;
@@ -14,6 +15,7 @@ use crate::printer::Printer;
 /// Clear the cache, removing all entries or those linked to specific packages.
 pub(crate) fn cache_clean(
     packages: &[PackageName],
+    force: bool,
     cache: Cache,
     printer: Printer,
 ) -> Result<ExitStatus> {
@@ -25,7 +27,19 @@ pub(crate) fn cache_clean(
         )?;
         return Ok(ExitStatus::Success);
     }
-    let cache = cache.with_exclusive_lock()?;
+
+    let cache = if force {
+        // If `--force` is used, attempt to acquire the exclusive lock but do not block.
+        match cache.with_exclusive_lock_no_wait() {
+            Ok(cache) => cache,
+            Err(cache) => {
+                debug!("Cache is currently in use, proceeding due to `--force`");
+                cache
+            }
+        }
+    } else {
+        cache.with_exclusive_lock()?
+    };
 
     let summary = if packages.is_empty() {
         writeln!(

crates/uv/src/lib.rs

@@ -1010,7 +1010,7 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
         })
         | Commands::Clean(args) => {
             show_settings!(args);
-            commands::cache_clean(&args.package, cache, printer)
+            commands::cache_clean(&args.package, args.force, cache, printer)
         }
         Commands::Cache(CacheNamespace {
             command: CacheCommand::Prune(args),

crates/uv/tests/it/cache_clean.rs

@@ -35,6 +35,59 @@ fn clean_all() -> Result<()> {
     Ok(())
 }
 
+#[test]
+fn clean_force() -> Result<()> {
+    let context = TestContext::new("3.12").with_filtered_counts();
+
+    let requirements_txt = context.temp_dir.child("requirements.txt");
+    requirements_txt.write_str("typing-extensions\niniconfig")?;
+
+    // Install a requirement, to populate the cache.
+    context
+        .pip_sync()
+        .arg("requirements.txt")
+        .assert()
+        .success();
+
+    // When unlocked, `--force` should still take a lock
+    uv_snapshot!(context.filters(), context.clean().arg("--verbose").arg("--force"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    DEBUG uv [VERSION] ([COMMIT] DATE)
+    DEBUG Acquired lock for `[CACHE_DIR]/`
+    Clearing cache at: [CACHE_DIR]/
+    DEBUG Released lock at `[CACHE_DIR]/.lock`
+    Removed [N] files ([SIZE])
+    ");
+
+    // Install a requirement, to re-populate the cache.
+    context
+        .pip_sync()
+        .arg("requirements.txt")
+        .assert()
+        .success();
+
+    // When locked, `--force` should proceed without blocking
+    let _cache = uv_cache::Cache::from_path(&context.cache_dir.path()).with_exclusive_lock();
+    uv_snapshot!(context.filters(), context.clean().arg("--verbose").arg("--force"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    DEBUG uv [VERSION] ([COMMIT] DATE)
+    DEBUG Lock is busy for `[CACHE_DIR]/`
+    DEBUG Cache is currently in use, proceeding due to `--force`
+    Clearing cache at: [CACHE_DIR]/
+    Removed [N] files ([SIZE])
+    ");
+
+    Ok(())
+}
+
 /// `cache clean iniconfig` should remove a single package (`iniconfig`).
 #[test]
 fn clean_package_pypi() -> Result<()> {