Add `uv sync --no-install-package` to skip installation of specific packages (#6540)

Extends #6538 / #6539
See #4028

Allows excluding arbitrary packages from the sync.

crates/uv-cli/src/lib.rs

@@ -2292,6 +2292,14 @@ pub struct SyncArgs {
     #[arg(long)]
     pub no_install_workspace: bool,
 
+    /// Do not install the given package(s).
+    ///
+    /// By default, all of the project's dependencies are installed into the environment. The
+    /// `--no-install-package` option allows exclusion of specific packages. Note this can result
+    /// in a broken environment, and should be used with caution.
+    #[arg(long)]
+    pub no_install_package: Vec<PackageName>,
+
     /// Assert that the `uv.lock` will remain unchanged.
     ///
     /// Requires that the lockfile is up-to-date. If the lockfile is missing or

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

@@ -596,6 +596,9 @@ pub(crate) async fn add(
 
     // Initialize any shared state.
     let state = SharedState::default();
+    let no_install_root = false;
+    let no_install_workspace = false;
+    let no_install_package = vec![];
 
     if let Err(err) = project::sync::do_sync(
         &project,
@@ -603,8 +606,9 @@ pub(crate) async fn add(
         &lock,
         &extras,
         dev,
-        false,
+        no_install_root,
-        false,
+        no_install_workspace,
+        no_install_package,
         Modifications::Sufficient,
         settings.as_ref().into(),
         &state,

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

@@ -192,6 +192,7 @@ pub(crate) async fn remove(
     let dev = true;
     let no_install_project = false;
     let no_install_workspace = false;
+    let no_install_package = vec![];
 
     // Initialize any shared state.
     let state = SharedState::default();
@@ -204,6 +205,7 @@ pub(crate) async fn remove(
         dev,
         no_install_project,
         no_install_workspace,
+        no_install_package,
         Modifications::Exact,
         settings.as_ref().into(),
         &state,

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

@@ -411,14 +411,19 @@ pub(crate) async fn run(
                 Err(err) => return Err(err.into()),
             };
 
+            let no_install_root = false;
+            let no_install_workspace = false;
+            let no_install_package = vec![];
+
             project::sync::do_sync(
                 &project,
                 &venv,
                 result.lock(),
                 &extras,
                 dev,
-                false,
+                no_install_root,
-                false,
+                no_install_workspace,
+                no_install_package,
                 Modifications::Sufficient,
                 settings.as_ref().into(),
                 &state,

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

@@ -2,6 +2,7 @@ use anyhow::{Context, Result};
 use distribution_types::Name;
 use itertools::Itertools;
 use pep508_rs::MarkerTree;
+use rustc_hash::FxHashSet;
 use tracing::debug;
 use uv_auth::store_credentials_from_url;
 use uv_cache::Cache;
@@ -34,6 +35,7 @@ pub(crate) async fn sync(
     dev: bool,
     no_install_project: bool,
     no_install_workspace: bool,
+    no_install_package: Vec<PackageName>,
     modifications: Modifications,
     python: Option<String>,
     python_preference: PythonPreference,
@@ -108,6 +110,7 @@ pub(crate) async fn sync(
         dev,
         no_install_project,
         no_install_workspace,
+        no_install_package,
         modifications,
         settings.as_ref().into(),
         &state,
@@ -133,6 +136,7 @@ pub(super) async fn do_sync(
     dev: bool,
     no_install_project: bool,
     no_install_workspace: bool,
+    no_install_package: Vec<PackageName>,
     modifications: Modifications,
     settings: InstallerSettingsRef<'_>,
     state: &SharedState,
@@ -202,6 +206,9 @@ pub(super) async fn do_sync(
     // If `--no-install-workspace` is set, remove the project and any workspace members.
     let resolution = apply_no_install_workspace(no_install_workspace, resolution, project);
 
+    // If `--no-install-package` is provided, remove the requested packages.
+    let resolution = apply_no_install_package(&no_install_package, resolution);
+
     // Add all authenticated sources to the cache.
     for url in index_locations.urls() {
         store_credentials_from_url(url);
@@ -321,3 +328,16 @@ fn apply_no_install_workspace(
         !workspace_packages.contains_key(dist.name()) && Some(dist.name()) != project.project_name()
     })
 }
+
+fn apply_no_install_package(
+    no_install_package: &[PackageName],
+    resolution: distribution_types::Resolution,
+) -> distribution_types::Resolution {
+    if no_install_package.is_empty() {
+        return resolution;
+    }
+
+    let no_install_packages = no_install_package.iter().collect::<FxHashSet<_>>();
+
+    resolution.filter(|dist| !no_install_packages.contains(dist.name()))
+}

crates/uv/src/lib.rs

@@ -1104,6 +1104,7 @@ async fn run_project(
                 args.dev,
                 args.no_install_project,
                 args.no_install_workspace,
+                args.no_install_package,
                 args.modifications,
                 args.python,
                 globals.python_preference,

crates/uv/src/settings.rs

@@ -619,6 +619,7 @@ pub(crate) struct SyncSettings {
     pub(crate) dev: bool,
     pub(crate) no_install_project: bool,
     pub(crate) no_install_workspace: bool,
+    pub(crate) no_install_package: Vec<PackageName>,
     pub(crate) modifications: Modifications,
     pub(crate) package: Option<PackageName>,
     pub(crate) python: Option<String>,
@@ -640,6 +641,7 @@ impl SyncSettings {
             exact,
             no_install_project,
             no_install_workspace,
+            no_install_package,
             locked,
             frozen,
             installer,
@@ -674,6 +676,7 @@ impl SyncSettings {
             dev: flag(dev, no_dev).unwrap_or(true),
             no_install_project,
             no_install_workspace,
+            no_install_package,
             modifications,
             package,
             python,

crates/uv/tests/sync.rs

@@ -864,8 +864,8 @@ fn no_install_project() -> Result<()> {
     Ok(())
 }
 
-/// Avoid syncing local dependencies for workspace dependencies when `--no-install-project` is provided, but
+/// Avoid syncing workspace members and the project when `--no-install-workspace` is provided, but
-/// include the workspace dependency's dependencies.
+/// include the all of the dependencies.
 #[test]
 fn no_install_workspace() -> Result<()> {
     let context = TestContext::new("3.12");
@@ -930,3 +930,56 @@ fn no_install_workspace() -> Result<()> {
 
     Ok(())
 }
+
+/// Avoid syncing the target package when `--no-install-package` is provided.
+#[test]
+fn no_install_package() -> Result<()> {
+    let context = TestContext::new("3.12");
+
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(
+        r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = ["anyio==3.7.0"]
+        "#,
+    )?;
+
+    // Generate a lockfile.
+    context.lock().assert().success();
+
+    // Running with `--no-install-package anyio` should skip anyio but include everything else
+    uv_snapshot!(context.filters(), context.sync().arg("--no-install-package").arg("anyio"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 4 packages in [TIME]
+    Prepared 3 packages in [TIME]
+    Installed 3 packages in [TIME]
+     + idna==3.6
+     + project==0.1.0 (from file://[TEMP_DIR]/)
+     + sniffio==1.3.1
+    "###);
+
+    // Running with `--no-install-package project` should skip the project itself (not as a special
+    // case, that's just the name of the project)
+    uv_snapshot!(context.filters(), context.sync().arg("--no-install-package").arg("project"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 4 packages in [TIME]
+    Prepared 1 package in [TIME]
+    Uninstalled 1 package in [TIME]
+    Installed 1 package in [TIME]
+     + anyio==3.7.0
+     - project==0.1.0 (from file://[TEMP_DIR]/)
+    "###);
+
+    Ok(())
+}

docs/guides/integration/docker.md

@@ -219,5 +219,7 @@ RUN uv sync --frozen
 
 !!! tip
 
-    If you're using a [workspace](../../concepts/workspaces.md), then consider the
+    If you're using a [workspace](../../concepts/workspaces.md), then use the
     `--no-install-workspace` flag which excludes the project _and_ any workspace members.
+
+    If you want to remove specific packages from the sync, use `--no-install-package <name>`.

docs/reference/cli.md

@@ -1170,6 +1170,10 @@ uv sync [OPTIONS]
 
 </dd><dt><code>--no-index</code></dt><dd><p>Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via <code>--find-links</code></p>
 
+</dd><dt><code>--no-install-package</code> <i>no-install-package</i></dt><dd><p>Do not install the given package(s).</p>
+
+<p>By default, all of the project&#8217;s dependencies are installed into the environment. The <code>--no-install-package</code> option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.</p>
+
 </dd><dt><code>--no-install-project</code></dt><dd><p>Do not install the current project.</p>
 
 <p>By default, the current project is installed into the environment with all of its dependencies. The <code>--no-install-project</code> option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.</p>