Introduce a --fork-strategy preference mode

crates/uv-cli/src/lib.rs

@@ -19,7 +19,7 @@ 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, ForkStrategy, PrereleaseMode, ResolutionMode};
 use uv_static::EnvVars;
 
 pub mod comma;
@@ -4045,6 +4045,24 @@ 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`), while minimizing the number of selected
+    /// versions across platforms.
+    ///
+    /// 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_FORK_STRATEGY,
+        help_heading = "Resolver options"
+    )]
+    pub fork_strategy: Option<ForkStrategy>,
+
     /// Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
     #[arg(
         long,
@@ -4834,6 +4852,24 @@ 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`), while minimizing the number of selected
+    /// versions across platforms.
+    ///
+    /// 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_FORK_STRATEGY,
+        help_heading = "Resolver options"
+    )]
+    pub fork_strategy: Option<ForkStrategy>,
+
     /// Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
     #[arg(
         long,
@@ -5006,6 +5042,24 @@ 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`), while minimizing the number of selected
+    /// versions across platforms.
+    ///
+    /// 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_FORK_STRATEGY,
+        help_heading = "Resolver options"
+    )]
+    pub fork_strategy: Option<ForkStrategy>,
+
     /// 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,
+            fork_strategy,
             config_setting,
             no_build_isolation,
             no_build_isolation_package,
@@ -58,6 +59,7 @@ impl From<ResolverArgs> for PipOptions {
             index_strategy,
             keyring_provider,
             resolution,
+            fork_strategy,
             prerelease: if pre {
                 Some(PrereleaseMode::Allow)
             } else {
@@ -126,6 +128,7 @@ impl From<ResolverInstallerArgs> for PipOptions {
             resolution,
             prerelease,
             pre,
+            fork_strategy,
             config_setting,
             no_build_isolation,
             no_build_isolation_package,
@@ -150,6 +153,7 @@ impl From<ResolverInstallerArgs> for PipOptions {
             } else {
                 prerelease
             },
+            fork_strategy,
             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,
+        fork_strategy,
         config_setting,
         no_build_isolation,
         no_build_isolation_package,
@@ -291,6 +296,7 @@ pub fn resolver_options(
         } else {
             prerelease
         },
+        fork_strategy,
         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,
+        fork_strategy,
         config_setting,
         no_build_isolation,
         no_build_isolation_package,
@@ -392,6 +399,7 @@ pub fn resolver_installer_options(
         } else {
             prerelease
         },
+        fork_strategy,
         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/fork_strategy.rs

@@ -0,0 +1,23 @@
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, serde::Deserialize, serde::Serialize)]
+#[serde(deny_unknown_fields, rename_all = "kebab-case")]
+#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub enum ForkStrategy {
+    /// Optimize for selecting the fewest number of versions for each package. Older versions may
+    /// be preferred if they are compatible with a wider range of supported Python versions or
+    /// platforms.
+    Fewest,
+    /// Optimize for selecting latest supported version of each package, for each supported Python
+    /// version.
+    #[default]
+    RequiresPython,
+}
+
+impl std::fmt::Display for ForkStrategy {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Fewest => write!(f, "fewest"),
+            Self::RequiresPython => write!(f, "requires-python"),
+        }
+    }
+}

crates/uv-resolver/src/lib.rs

@@ -3,6 +3,7 @@ pub use error::{NoSolutionError, NoSolutionHeader, ResolveError, SentinelRange};
 pub use exclude_newer::ExcludeNewer;
 pub use exclusions::Exclusions;
 pub use flat_index::{FlatDistributions, FlatIndex};
+pub use fork_strategy::ForkStrategy;
 pub use lock::{
     InstallTarget, Lock, LockError, LockVersion, PackageMap, RequirementsTxtExport,
     ResolverManifest, SatisfiesResult, TreeDisplay, VERSION,
@@ -41,6 +42,7 @@ mod exclude_newer;
 mod exclusions;
 mod flat_index;
 mod fork_indexes;
+mod fork_strategy;
 mod fork_urls;
 mod graph_ops;
 mod lock;

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

@@ -13,6 +13,7 @@ use std::sync::{Arc, LazyLock};
 use toml_edit::{value, Array, ArrayOfTables, InlineTable, Item, Table, Value};
 use url::Url;
 
+use crate::fork_strategy::ForkStrategy;
 pub use crate::lock::map::PackageMap;
 pub use crate::lock::requirements_txt::RequirementsTxtExport;
 pub use crate::lock::target::InstallTarget;
@@ -239,6 +240,7 @@ impl Lock {
         let options = ResolverOptions {
             resolution_mode: resolution.options.resolution_mode,
             prerelease_mode: resolution.options.prerelease_mode,
+            fork_strategy: resolution.options.fork_strategy,
             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 fork_strategy(&self) -> ForkStrategy {
+        self.options.fork_strategy
+    }
+
     /// 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.fork_strategy != ForkStrategy::default() {
+                options_table.insert(
+                    "fork-strategy",
+                    value(self.options.fork_strategy.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 [`ForkStrategy`] used to generate this lock.
+    #[serde(default)]
+    fork_strategy: ForkStrategy,
     /// 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

@@ -1,5 +1,5 @@
 ---
-source: crates/uv-resolver/src/lock/tests.rs
+source: crates/uv-resolver/src/lock/mod.rs
 expression: result
 ---
 Ok(
@@ -33,6 +33,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            fork_strategy: RequiresPython,
             exclude_newer: None,
         },
         packages: [

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

@@ -1,5 +1,5 @@
 ---
-source: crates/uv-resolver/src/lock/tests.rs
+source: crates/uv-resolver/src/lock/mod.rs
 expression: result
 ---
 Ok(
@@ -33,6 +33,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            fork_strategy: RequiresPython,
             exclude_newer: None,
         },
         packages: [

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

@@ -1,5 +1,5 @@
 ---
-source: crates/uv-resolver/src/lock/tests.rs
+source: crates/uv-resolver/src/lock/mod.rs
 expression: result
 ---
 Ok(
@@ -33,6 +33,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            fork_strategy: RequiresPython,
             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,
+            fork_strategy: RequiresPython,
             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,
+            fork_strategy: RequiresPython,
             exclude_newer: None,
         },
         packages: [

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

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

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

@@ -1,5 +1,5 @@
 ---
-source: crates/uv-resolver/src/lock/tests.rs
+source: crates/uv-resolver/src/lock/mod.rs
 expression: result
 ---
 Ok(
@@ -33,6 +33,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            fork_strategy: RequiresPython,
             exclude_newer: None,
         },
         packages: [

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

@@ -1,5 +1,5 @@
 ---
-source: crates/uv-resolver/src/lock/tests.rs
+source: crates/uv-resolver/src/lock/mod.rs
 expression: result
 ---
 Ok(
@@ -33,6 +33,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            fork_strategy: RequiresPython,
             exclude_newer: None,
         },
         packages: [

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

@@ -1,5 +1,5 @@
 ---
-source: crates/uv-resolver/src/lock/tests.rs
+source: crates/uv-resolver/src/lock/mod.rs
 expression: result
 ---
 Ok(
@@ -33,6 +33,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            fork_strategy: RequiresPython,
             exclude_newer: None,
         },
         packages: [

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

@@ -1,5 +1,5 @@
 ---
-source: crates/uv-resolver/src/lock/tests.rs
+source: crates/uv-resolver/src/lock/mod.rs
 expression: result
 ---
 Ok(
@@ -33,6 +33,7 @@ Ok(
         options: ResolverOptions {
             resolution_mode: Highest,
             prerelease_mode: IfNecessaryOrExplicit,
+            fork_strategy: RequiresPython,
             exclude_newer: None,
         },
         packages: [