uv sync --no-clean (#4367)

## Summary

Adds a `--no-clean` flag to `uv sync` that keeps extraneous
installations. This is the default in `uv run` and `uv add`, but not in
`uv sync` or `uv remove`. This means you need to run an explicit `uv
sync/remove` to clean the virtual environment.

crates/uv/src/cli.rs

@@ -1544,6 +1544,11 @@ pub(crate) struct SyncArgs {
     #[arg(long, overrides_with("dev"))]
     pub(crate) no_dev: bool,
 
+    /// Does not clean the environment.
+    /// Without this flag any extraneous installations will be removed.
+    #[arg(long)]
+    pub(crate) no_clean: bool,
+
     #[command(flatten)]
     pub(crate) installer: InstallerArgs,
 

crates/uv/src/commands/mod.rs

@@ -40,7 +40,7 @@ use crate::printer::Printer;
 mod cache_clean;
 mod cache_dir;
 mod cache_prune;
-mod pip;
+pub(crate) mod pip;
 mod project;
 pub(crate) mod reporters;
 mod tool;

crates/uv/src/commands/project/add.rs

@@ -12,6 +12,7 @@ use uv_configuration::{Concurrency, ExtrasSpecification, PreviewMode, SetupPyStr
 use uv_distribution::{DistributionDatabase, ProjectWorkspace};
 use uv_warnings::warn_user;
 
+use crate::commands::pip::operations::Modifications;
 use crate::commands::pip::resolution_environment;
 use crate::commands::reporters::ResolverReporter;
 use crate::commands::{project, ExitStatus};
@@ -172,6 +173,7 @@ pub(crate) async fn add(
         &lock,
         extras,
         dev,
+        Modifications::Sufficient,
         &settings.reinstall,
         &settings.index_locations,
         &settings.index_strategy,

crates/uv/src/commands/project/remove.rs

@@ -8,6 +8,7 @@ use uv_distribution::pyproject_mut::PyProjectTomlMut;
 use uv_distribution::ProjectWorkspace;
 use uv_warnings::warn_user;
 
+use crate::commands::pip::operations::Modifications;
 use crate::commands::{project, ExitStatus};
 use crate::printer::Printer;
 use crate::settings::{InstallerSettings, ResolverSettings};
@@ -121,6 +122,7 @@ pub(crate) async fn remove(
         &lock,
         extras,
         dev,
+        Modifications::Exact,
         &settings.reinstall,
         &settings.index_locations,
         &settings.index_strategy,

crates/uv/src/commands/project/run.rs

@@ -15,6 +15,7 @@ use uv_requirements::RequirementsSource;
 use uv_toolchain::{PythonEnvironment, SystemPython, Toolchain, ToolchainRequest};
 use uv_warnings::warn_user;
 
+use crate::commands::pip::operations::Modifications;
 use crate::commands::{project, ExitStatus};
 use crate::printer::Printer;
 use crate::settings::ResolverInstallerSettings;
@@ -91,6 +92,7 @@ pub(crate) async fn run(
             &lock,
             extras,
             dev,
+            Modifications::Sufficient,
             &settings.reinstall,
             &settings.index_locations,
             &settings.index_strategy,

crates/uv/src/commands/project/sync.rs

@@ -31,6 +31,7 @@ use crate::settings::InstallerSettings;
 pub(crate) async fn sync(
     extras: ExtrasSpecification,
     dev: bool,
+    modifications: Modifications,
     python: Option<String>,
     settings: InstallerSettings,
     preview: PreviewMode,
@@ -65,6 +66,7 @@ pub(crate) async fn sync(
         &lock,
         extras,
         dev,
+        modifications,
         &settings.reinstall,
         &settings.index_locations,
         &settings.index_strategy,
@@ -94,6 +96,7 @@ pub(super) async fn do_sync(
     lock: &Lock,
     extras: ExtrasSpecification,
     dev: bool,
+    modifications: Modifications,
     reinstall: &Reinstall,
     index_locations: &IndexLocations,
     index_strategy: &IndexStrategy,
@@ -188,7 +191,7 @@ pub(super) async fn do_sync(
     pip::operations::install(
         &resolution,
         site_packages,
-        Modifications::Exact,
+        modifications,
         reinstall,
         build_options,
         *link_mode,

crates/uv/src/main.rs

@@ -646,6 +646,7 @@ async fn run() -> Result<ExitStatus> {
             commands::sync(
                 args.extras,
                 args.dev,
+                args.modifications,
                 args.python,
                 args.settings,
                 globals.preview,

crates/uv/src/settings.rs

@@ -31,6 +31,7 @@ use crate::cli::{
     RunArgs, SyncArgs, ToolRunArgs, ToolchainFindArgs, ToolchainInstallArgs, ToolchainListArgs,
     VenvArgs,
 };
+use crate::commands::pip::operations::Modifications;
 use crate::commands::ListFormat;
 
 /// The resolved global settings to use for any invocation of the CLI.
@@ -297,6 +298,7 @@ impl ToolchainFindSettings {
 pub(crate) struct SyncSettings {
     pub(crate) extras: ExtrasSpecification,
     pub(crate) dev: bool,
+    pub(crate) modifications: Modifications,
     pub(crate) python: Option<String>,
     pub(crate) refresh: Refresh,
     pub(crate) settings: InstallerSettings,
@@ -312,18 +314,26 @@ impl SyncSettings {
             no_all_extras,
             dev,
             no_dev,
+            no_clean,
             installer,
             build,
             refresh,
             python,
         } = args;
 
+        let modifications = if no_clean {
+            Modifications::Sufficient
+        } else {
+            Modifications::Exact
+        };
+
         Self {
             extras: ExtrasSpecification::from_args(
                 flag(all_extras, no_all_extras).unwrap_or_default(),
                 extra.unwrap_or_default(),
             ),
             dev: flag(dev, no_dev).unwrap_or(true),
+            modifications,
             python,
             refresh: Refresh::from(refresh),
             settings: InstallerSettings::combine(installer_options(installer, build), filesystem),

crates/uv/tests/edit.rs

@@ -643,6 +643,149 @@ fn update_registry() -> Result<()> {
     Ok(())
 }
 
+/// Adding a dependency does not clean the environment.
+#[test]
+fn add_no_clean() -> Result<()> {
+    let context = TestContext::new("3.12");
+
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(indoc! {r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = [
+            "anyio == 3.7.0",
+        ]
+    "#})?;
+
+    uv_snapshot!(context.filters(), context.lock(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    warning: `uv lock` is experimental and may change without warning.
+    Resolved 4 packages in [TIME]
+    "###);
+
+    uv_snapshot!(context.filters(), context.sync(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    warning: `uv sync` is experimental and may change without warning.
+    Downloaded 4 packages in [TIME]
+    Installed 4 packages in [TIME]
+     + anyio==3.7.0
+     + idna==3.6
+     + project==0.1.0 (from file://[TEMP_DIR]/)
+     + sniffio==1.3.1
+    "###);
+
+    // Manually remove a dependency.
+    pyproject_toml.write_str(indoc! {r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = []
+    "#})?;
+
+    uv_snapshot!(context.filters(), context.add(&["iniconfig==2.0.0"]), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    warning: `uv add` is experimental and may change without warning.
+    Resolved 2 packages in [TIME]
+    Downloaded 2 packages in [TIME]
+    Uninstalled 1 package in [TIME]
+    Installed 2 packages in [TIME]
+     + iniconfig==2.0.0
+     - project==0.1.0 (from file://[TEMP_DIR]/)
+     + project==0.1.0 (from file://[TEMP_DIR]/)
+    "###);
+
+    let pyproject_toml = fs_err::read_to_string(context.temp_dir.join("pyproject.toml"))?;
+
+    insta::with_settings!({
+        filters => context.filters(),
+    }, {
+        assert_snapshot!(
+            pyproject_toml, @r###"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = [
+            "iniconfig==2.0.0",
+        ]
+        "###
+        );
+    });
+
+    let lock = fs_err::read_to_string(context.temp_dir.join("uv.lock"))?;
+
+    insta::with_settings!({
+        filters => context.filters(),
+    }, {
+        assert_snapshot!(
+            lock, @r###"
+        version = 1
+        requires-python = ">=3.12"
+
+        [[distribution]]
+        name = "iniconfig"
+        version = "2.0.0"
+        source = "registry+https://pypi.org/simple"
+        sdist = { url = "https://files.pythonhosted.org/packages/d7/4b/cbd8e699e64a6f16ca3a8220661b5f83792b3017d0f79807cb8708d33913/iniconfig-2.0.0.tar.gz", hash = "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3", size = 4646 }
+        wheels = [{ url = "https://files.pythonhosted.org/packages/ef/a6/62565a6e1cf69e10f5727360368e451d4b7f58beeac6173dc9db836a5b46/iniconfig-2.0.0-py3-none-any.whl", hash = "sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374", size = 5892 }]
+
+        [[distribution]]
+        name = "project"
+        version = "0.1.0"
+        source = "editable+."
+        sdist = { path = "." }
+
+        [[distribution.dependencies]]
+        name = "iniconfig"
+        version = "2.0.0"
+        source = "registry+https://pypi.org/simple"
+        "###
+        );
+    });
+
+    // Install from the lockfile without cleaning the environment.
+    uv_snapshot!(context.filters(), context.sync().arg("--no-clean"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    warning: `uv sync` is experimental and may change without warning.
+    Audited 2 packages in [TIME]
+    "###);
+
+    // Install from the lockfile, cleaning the environment.
+    uv_snapshot!(context.filters(), context.sync(), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    warning: `uv sync` is experimental and may change without warning.
+    Uninstalled 3 packages in [TIME]
+     - anyio==3.7.0
+     - idna==3.6
+     - sniffio==1.3.1
+    "###);
+
+    Ok(())
+}
+
 /// Remove a PyPI requirement.
 #[test]
 fn remove_registry() -> Result<()> {