Introduce a --multi-version preference mode

Author: charliermarsh

crates/uv-cli/src/lib.rs

@@ -19,7 +19,9 @@ use uv_normalize::{ExtraName, GroupName, PackageName};
 use uv_pep508::Requirement;
 use uv_pypi_types::VerbatimParsedUrl;
 use uv_python::{PythonDownloads, PythonPreference, PythonVersion};
-use uv_resolver::{AnnotationStyle, ExcludeNewer, PrereleaseMode, ResolutionMode};
+use uv_resolver::{
+    AnnotationStyle, ExcludeNewer, MultiVersionMode, PrereleaseMode, ResolutionMode,
+};
 use uv_static::EnvVars;
 
 pub mod compat;
@@ -4413,6 +4415,20 @@ pub struct ResolverArgs {
     #[arg(long, hide = true, help_heading = "Resolver options")]
     pub pre: bool,
 
+    /// The strategy to use when selecting multiple versions of a given package across Python
+    /// versions and platforms.
+    ///
+    /// By default, uv will minimize the number of versions selected for each package (`fewest`),
+    /// to minimize differences between environments. Under `latest`, uv will select the latest
+    /// compatible version for each environment, even if it results in more versions being selected.
+    #[arg(
+        long,
+        value_enum,
+        env = EnvVars::UV_MULTI_VERSION,
+        help_heading = "Resolver options"
+    )]
+    pub multi_version: Option<MultiVersionMode>,
+
     /// Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
     #[arg(
         long,
@@ -4605,6 +4621,20 @@ pub struct ResolverInstallerArgs {
     #[arg(long, hide = true)]
     pub pre: bool,
 
+    /// The strategy to use when selecting multiple versions of a given package across Python
+    /// versions and platforms.
+    ///
+    /// By default, uv will minimize the number of versions selected for each package (`fewest`),
+    /// to minimize differences between environments. Under `latest`, uv will select the latest
+    /// compatible version for each environment, even if it results in more versions being selected.
+    #[arg(
+        long,
+        value_enum,
+        env = EnvVars::UV_MULTI_VERSION,
+        help_heading = "Resolver options"
+    )]
+    pub multi_version: Option<MultiVersionMode>,
+
     /// Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
     #[arg(
         long,

crates/uv-cli/src/options.rs

@@ -44,6 +44,7 @@ impl From<ResolverArgs> for PipOptions {
             resolution,
             prerelease,
             pre,
+            multi_version,
             config_setting,
             no_build_isolation,
             no_build_isolation_package,
@@ -65,6 +66,7 @@ impl From<ResolverArgs> for PipOptions {
                     .collect()
             }),
             resolution,
+            multi_version,
             prerelease: if pre {
                 Some(PrereleaseMode::Allow)
             } else {
@@ -141,6 +143,7 @@ impl From<ResolverInstallerArgs> for PipOptions {
             resolution,
             prerelease,
             pre,
+            multi_version,
             config_setting,
             no_build_isolation,
             no_build_isolation_package,
@@ -171,6 +174,7 @@ impl From<ResolverInstallerArgs> for PipOptions {
             } else {
                 prerelease
             },
+            multi_version,
             config_settings: config_setting
                 .map(|config_settings| config_settings.into_iter().collect::<ConfigSettings>()),
             no_build_isolation: flag(no_build_isolation, build_isolation),
@@ -239,6 +243,7 @@ pub fn resolver_options(
         resolution,
         prerelease,
         pre,
+        multi_version,
         config_setting,
         no_build_isolation,
         no_build_isolation_package,
@@ -301,6 +306,7 @@ pub fn resolver_options(
         } else {
             prerelease
         },
+        multi_version,
         dependency_metadata: None,
         config_settings: config_setting
             .map(|config_settings| config_settings.into_iter().collect::<ConfigSettings>()),
@@ -335,6 +341,7 @@ pub fn resolver_installer_options(
         resolution,
         prerelease,
         pre,
+        multi_version,
         config_setting,
         no_build_isolation,
         no_build_isolation_package,
@@ -409,6 +416,7 @@ pub fn resolver_installer_options(
         } else {
             prerelease
         },
+        multi_version,
         dependency_metadata: None,
         config_settings: config_setting
             .map(|config_settings| config_settings.into_iter().collect::<ConfigSettings>()),

crates/uv-resolver/src/lib.rs

@@ -8,6 +8,7 @@ pub use lock::{
     TreeDisplay, VERSION,
 };
 pub use manifest::Manifest;
+pub use multi_version_mode::MultiVersionMode;
 pub use options::{Flexibility, Options, OptionsBuilder};
 pub use preferences::{Preference, PreferenceError, Preferences};
 pub use prerelease::PrereleaseMode;
@@ -40,6 +41,7 @@ mod graph_ops;
 mod lock;
 mod manifest;
 mod marker;
+mod multi_version_mode;
 mod options;
 mod pins;
 mod preferences;

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

@@ -16,6 +16,7 @@ use url::Url;
 
 pub use crate::lock::requirements_txt::RequirementsTxtExport;
 pub use crate::lock::tree::TreeDisplay;
+use crate::multi_version_mode::MultiVersionMode;
 use crate::requires_python::SimplifiedMarkerTree;
 use crate::resolution::{AnnotatedDist, ResolutionGraphNode};
 use crate::{
@@ -226,6 +227,7 @@ impl Lock {
         let options = ResolverOptions {
             resolution_mode: graph.options.resolution_mode,
             prerelease_mode: graph.options.prerelease_mode,
+            multi_version_mode: graph.options.multi_version_mode,
             exclude_newer: graph.options.exclude_newer,
         };
         let lock = Self::new(
@@ -529,6 +531,11 @@ impl Lock {
         self.options.prerelease_mode
     }
 
+    /// Returns the multi-version mode used to generate this lock.
+    pub fn multi_version_mode(&self) -> MultiVersionMode {
+        self.options.multi_version_mode
+    }
+
     /// Returns the exclude newer setting used to generate this lock.
     pub fn exclude_newer(&self) -> Option<ExcludeNewer> {
         self.options.exclude_newer
@@ -753,6 +760,12 @@ impl Lock {
                     value(self.options.prerelease_mode.to_string()),
                 );
             }
+            if self.options.multi_version_mode != MultiVersionMode::default() {
+                options_table.insert(
+                    "multi-version-mode",
+                    value(self.options.multi_version_mode.to_string()),
+                );
+            }
             if let Some(exclude_newer) = self.options.exclude_newer {
                 options_table.insert("exclude-newer", value(exclude_newer.to_string()));
             }
@@ -1382,6 +1395,9 @@ struct ResolverOptions {
     /// The [`PrereleaseMode`] used to generate this lock.
     #[serde(default)]
     prerelease_mode: PrereleaseMode,
+    /// The [`MultiVersionMode`] used to generate this lock.
+    #[serde(default)]
+    multi_version_mode: MultiVersionMode,
     /// The [`ExcludeNewer`] used to generate this lock.
     exclude_newer: Option<ExcludeNewer>,
 }

crates/uv-resolver/src/lock/snapshots/uv_resolver__lock__tests__hash_optional_missing.snap

@@ -30,6 +30,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            multi_version_mode: Fewest,
             exclude_newer: None,
         },
         packages: [

crates/uv-resolver/src/lock/snapshots/uv_resolver__lock__tests__hash_optional_present.snap

@@ -30,6 +30,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            multi_version_mode: Fewest,
             exclude_newer: None,
         },
         packages: [

crates/uv-resolver/src/lock/snapshots/uv_resolver__lock__tests__hash_required_present.snap

@@ -30,6 +30,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            multi_version_mode: Fewest,
             exclude_newer: None,
         },
         packages: [

crates/uv-resolver/src/lock/snapshots/uv_resolver__lock__tests__missing_dependency_source_unambiguous.snap

@@ -30,6 +30,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            multi_version_mode: Fewest,
             exclude_newer: None,
         },
         packages: [

crates/uv-resolver/src/lock/snapshots/uv_resolver__lock__tests__missing_dependency_source_version_unambiguous.snap

@@ -30,6 +30,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            multi_version_mode: Fewest,
             exclude_newer: None,
         },
         packages: [

crates/uv-resolver/src/lock/snapshots/uv_resolver__lock__tests__missing_dependency_version_unambiguous.snap

@@ -30,6 +30,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            multi_version_mode: Fewest,
             exclude_newer: None,
         },
         packages: [