feat: export --prune (#9389)

## Summary

This adds a `--prune` flag to the `export` command to correspond with
the `--prune` flag of the `tree` command.

The purpose is for generating a `requirements.txt` that omits a package
and all of that package's unique dependencies. This is useful for cases
where the project has a dependency on a common core package, but where
that package does not need to be installed in the target environment.

For example, a pyspark job needs spark for development, but when
installing into a cluster that already has pyspark installed, it is
desirable to omit pyspark's whole dependency tree so that only the
unique dependencies that your job needs get installed, and do not risk
breaking the pyspark dependencies with something incompatible.

Dev groups cannot always cover this case because there are other
projects where this common dependency occurs as a transitive. One
example is Airflow providers, which include Airflow itself as a
dependency, but it is unnecessary and undesirable to include Airflow's
dependency tree in the `requirements.txt` for your DAGs.

Partly related to #7214, though I'm not sure it covers the ask in that
one of having this functionality extend to the project's actual
published metadata.


## Test Plan

An integration test was added, and some manual testing. Let me know if
more would be better.

---------

Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>

crates/uv-cli/src/lib.rs

@@ -3401,6 +3401,13 @@ pub struct ExportArgs {
     #[arg(long, conflicts_with = "all_packages")]
     pub package: Option<PackageName>,
 
+    /// Prune the given package from the dependency tree.
+    ///
+    /// Pruned packages will be excluded from the exported requirements file, as will any
+    /// dependencies that are no longer required after the pruned package is removed.
+    #[arg(long, conflicts_with = "all_packages")]
+    pub prune: Vec<PackageName>,
+
     /// Include optional dependencies from the specified extra name.
     ///
     /// May be provided more than once.

crates/uv-resolver/src/lock/requirements_txt.rs

@@ -14,7 +14,7 @@ use uv_configuration::{DevGroupsManifest, EditableMode, ExtrasSpecification, Ins
 use uv_distribution_filename::{DistExtension, SourceDistExtension};
 use uv_fs::Simplified;
 use uv_git::GitReference;
-use uv_normalize::ExtraName;
+use uv_normalize::{ExtraName, PackageName};
 use uv_pep508::MarkerTree;
 use uv_pypi_types::{ParsedArchiveUrl, ParsedGitUrl};
 
@@ -34,6 +34,7 @@ pub struct RequirementsTxtExport<'lock> {
 impl<'lock> RequirementsTxtExport<'lock> {
     pub fn from_lock(
         target: InstallTarget<'lock>,
+        prune: &[PackageName],
         extras: &ExtrasSpecification,
         dev: &DevGroupsManifest,
         editable: EditableMode,
@@ -54,6 +55,10 @@ impl<'lock> RequirementsTxtExport<'lock> {
 
         // Add the workspace package to the queue.
         for root_name in target.packages() {
+            if prune.contains(root_name) {
+                continue;
+            }
+
             let dist = target
                 .lock()
                 .find_by_name(root_name)
@@ -100,6 +105,10 @@ impl<'lock> RequirementsTxtExport<'lock> {
                 })
                 .flatten()
             {
+                if prune.contains(&dep.package_id.name) {
+                    continue;
+                }
+
                 let dep_dist = target.lock().find_by_id(&dep.package_id);
 
                 // Add the dependency to the graph.
@@ -156,6 +165,10 @@ impl<'lock> RequirementsTxtExport<'lock> {
             };
 
             for dep in deps {
+                if prune.contains(&dep.package_id.name) {
+                    continue;
+                }
+
                 let dep_dist = target.lock().find_by_id(&dep.package_id);
 
                 // Add the dependency to the graph.

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

@@ -34,6 +34,7 @@ pub(crate) async fn export(
     format: ExportFormat,
     all_packages: bool,
     package: Option<PackageName>,
+    prune: Vec<PackageName>,
     hashes: bool,
     install_options: InstallOptions,
     output_file: Option<PathBuf>,
@@ -183,6 +184,7 @@ pub(crate) async fn export(
         ExportFormat::RequirementsTxt => {
             let export = RequirementsTxtExport::from_lock(
                 target,
+                &prune,
                 &extras,
                 &dev,
                 editable,

crates/uv/src/lib.rs

@@ -1570,6 +1570,7 @@ async fn run_project(
                 args.format,
                 args.all_packages,
                 args.package,
+                args.prune,
                 args.hashes,
                 args.install_options,
                 args.output_file,

crates/uv/src/settings.rs

@@ -1279,6 +1279,7 @@ pub(crate) struct ExportSettings {
     pub(crate) format: ExportFormat,
     pub(crate) all_packages: bool,
     pub(crate) package: Option<PackageName>,
+    pub(crate) prune: Vec<PackageName>,
     pub(crate) extras: ExtrasSpecification,
     pub(crate) dev: DevGroupsSpecification,
     pub(crate) editable: EditableMode,
@@ -1302,6 +1303,7 @@ impl ExportSettings {
             format,
             all_packages,
             package,
+            prune,
             extra,
             all_extras,
             no_all_extras,
@@ -1337,6 +1339,7 @@ impl ExportSettings {
             format,
             all_packages,
             package,
+            prune,
             extras: ExtrasSpecification::from_args(
                 flag(all_extras, no_all_extras).unwrap_or_default(),
                 extra.unwrap_or_default(),

crates/uv/tests/it/export.rs

@@ -254,6 +254,63 @@ fn project_extra() -> Result<()> {
     Ok(())
 }
 
+#[test]
+fn prune() -> 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 = [
+            "jupyter-client"
+        ]
+    "#,
+    )?;
+
+    // project v0.1.0
+    // └── jupyter-client v8.6.1
+    //     ├── jupyter-core v5.7.2
+    //     │   ├── platformdirs v4.2.0
+    //     │   └── traitlets v5.14.2
+    //     ├── python-dateutil v2.9.0.post0
+    //     │   └── six v1.16.0
+    //     ├── pyzmq v25.1.2
+    //     ├── tornado v6.4
+    //     └── traitlets v5.14.2
+
+    uv_snapshot!(
+        context.filters(),
+        context.export()
+            .arg("--no-hashes")
+            .arg("--prune")
+            .arg("jupyter-core"),
+            @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    # This file was autogenerated by uv via the following command:
+    #    uv export --cache-dir [CACHE_DIR] --no-hashes --prune jupyter-core
+    cffi==1.16.0 ; implementation_name == 'pypy'
+    jupyter-client==8.6.1
+    pycparser==2.21 ; implementation_name == 'pypy'
+    python-dateutil==2.9.0.post0
+    pyzmq==25.1.2
+    six==1.16.0
+    tornado==6.4
+    traitlets==5.14.2
+
+    ----- stderr -----
+    Resolved 12 packages in [TIME]
+    "
+    );
+
+    Ok(())
+}
+
 #[test]
 fn dependency_marker() -> Result<()> {
     let context = TestContext::new("3.12");

docs/reference/cli.md

@@ -2355,6 +2355,10 @@ uv export [OPTIONS]
 
 <p>This setting has no effect when used in the <code>uv pip</code> interface.</p>
 
+</dd><dt><code>--prune</code> <i>prune</i></dt><dd><p>Prune the given package from the dependency tree.</p>
+
+<p>Pruned packages will be excluded from the exported requirements file, as will any dependencies that are no longer required after the pruned package is removed.</p>
+
 </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use during resolution.</p>
 
 <p>A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.</p>