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 comma;
@@ -4045,6 +4047,21 @@ pub struct ToolUpgradeArgs {
     #[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 optimize for selecting the latest version of each package, for each
+    /// supported Python version (`requires-python`). Under `fewest`, uv will minimize the number of
+    /// selected versions for each package, preferring older versions that are compatible with a
+    /// wider range of supported Python versions or platforms.
+    #[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,
@@ -4834,6 +4851,21 @@ 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 optimize for selecting the latest version of each package, for each
+    /// supported Python version (`requires-python`). Under `fewest`, uv will minimize the number of
+    /// selected versions for each package, preferring older versions that are compatible with a
+    /// wider range of supported Python versions or platforms.
+    #[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,
@@ -5006,6 +5038,21 @@ 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 optimize for selecting the latest version of each package, for each
+    /// supported Python version (`requires-python`). Under `fewest`, uv will minimize the number of
+    /// selected versions for each package, preferring older versions that are compatible with a
+    /// wider range of supported Python versions or platforms.
+    #[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

@@ -43,6 +43,7 @@ impl From<ResolverArgs> for PipOptions {
             resolution,
             prerelease,
             pre,
+            multi_version,
             config_setting,
             no_build_isolation,
             no_build_isolation_package,
@@ -58,6 +59,7 @@ impl From<ResolverArgs> for PipOptions {
             index_strategy,
             keyring_provider,
             resolution,
+            multi_version,
             prerelease: if pre {
                 Some(PrereleaseMode::Allow)
             } else {
@@ -126,6 +128,7 @@ impl From<ResolverInstallerArgs> for PipOptions {
             resolution,
             prerelease,
             pre,
+            multi_version,
             config_setting,
             no_build_isolation,
             no_build_isolation_package,
@@ -150,6 +153,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),
@@ -235,6 +239,7 @@ pub fn resolver_options(
         resolution,
         prerelease,
         pre,
+        multi_version,
         config_setting,
         no_build_isolation,
         no_build_isolation_package,
@@ -291,6 +296,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>()),
@@ -324,6 +330,7 @@ pub fn resolver_installer_options(
         resolution,
         prerelease,
         pre,
+        multi_version,
         config_setting,
         no_build_isolation,
         no_build_isolation_package,
@@ -392,6 +399,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-python/src/python_version.rs

@@ -50,7 +50,9 @@ impl schemars::JsonSchema for PythonVersion {
                 ..schemars::schema::StringValidation::default()
             })),
             metadata: Some(Box::new(schemars::schema::Metadata {
-                description: Some("A Python version specifier, e.g. `3.7` or `3.8.0`.".to_string()),
+                description: Some(
+                    "A Python version specifier, e.g. `3.11` or `3.12.4`.".to_string(),
+                ),
                 ..schemars::schema::Metadata::default()
             })),
             ..schemars::schema::SchemaObject::default()

crates/uv-resolver/src/lib.rs

@@ -8,6 +8,7 @@ pub use lock::{
     ResolverManifest, SatisfiesResult, 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;
@@ -46,6 +47,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

@@ -17,6 +17,7 @@ pub use crate::lock::map::PackageMap;
 pub use crate::lock::requirements_txt::RequirementsTxtExport;
 pub use crate::lock::target::InstallTarget;
 pub use crate::lock::tree::TreeDisplay;
+use crate::multi_version_mode::MultiVersionMode;
 use crate::requires_python::SimplifiedMarkerTree;
 use crate::resolution::{AnnotatedDist, ResolutionGraphNode};
 use crate::universal_marker::{ConflictMarker, UniversalMarker};
@@ -239,6 +240,7 @@ impl Lock {
         let options = ResolverOptions {
             resolution_mode: resolution.options.resolution_mode,
             prerelease_mode: resolution.options.prerelease_mode,
+            multi_version_mode: resolution.options.multi_version_mode,
             exclude_newer: resolution.options.exclude_newer,
         };
         let lock = Self::new(
@@ -548,6 +550,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
@@ -675,6 +682,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()));
             }
@@ -1317,6 +1330,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

@@ -33,6 +33,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

@@ -33,6 +33,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

@@ -33,6 +33,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

@@ -33,6 +33,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

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