Hint at tool.uv.environments on resolution error

Users are not (yet) properly familiar with the concept of universal resolution and its implication that we need to resolve for all possible platforms and Python versions. Some projects only target a specific platform or Python version and experience resolution errors due to failures for other platforms. Indicated by the number of questions we get about it, `too.uv.environments` for restricting environments is not well discoverable.

We add a special hint when resolution failed on a fork disjoint with the current environment, hinting the user to constraint `requires-python` and `tool.uv.environments` respectively.

The hint has false positives for cases where the resolution failed on a different platform, but equally fails on the current platform, but the other fork was earlier. Given that conflicts can be based on `requires-python`, afaik be can't parse whether the current platform would also be affected from the derivation tree.

Two cases not covered by this are build errors as well as install error that need `tool.uv.required-environments`.

Author: konstin

crates/uv-bench/benches/uv.rs

@@ -206,6 +206,7 @@ mod resolver {
             options,
             &python_requirement,
             markers,
+            interpreter.markers(),
             conflicts,
             Some(&TAGS),
             &flat_index,

crates/uv-dispatch/src/lib.rs

@@ -226,6 +226,7 @@ impl BuildContext for BuildDispatch<'_> {
                 .build(),
             &python_requirement,
             ResolverEnvironment::specific(marker_env),
+            self.interpreter.markers(),
             // Conflicting groups only make sense when doing universal resolution.
             Conflicts::empty(),
             Some(tags),

crates/uv-resolver/src/error.rs

@@ -3,6 +3,7 @@ use std::fmt::Formatter;
 use std::sync::Arc;
 
 use indexmap::IndexSet;
+use owo_colors::OwoColorize;
 use pubgrub::{
     DefaultStringReporter, DerivationTree, Derived, External, Range, Ranges, Reporter, Term,
 };
@@ -13,7 +14,8 @@ use uv_distribution_types::{
     DerivationChain, DistErrorKind, IndexCapabilities, IndexLocations, IndexUrl, RequestedDist,
 };
 use uv_normalize::{ExtraName, InvalidNameError, PackageName};
-use uv_pep440::{LocalVersionSlice, LowerBound, Version};
+use uv_pep440::{LocalVersionSlice, LowerBound, Version, VersionSpecifier};
+use uv_pep508::{MarkerEnvironment, MarkerExpression, MarkerTree, MarkerValueVersion};
 use uv_platform_tags::Tags;
 use uv_static::EnvVars;
 
@@ -157,6 +159,7 @@ pub struct NoSolutionError {
     fork_urls: ForkUrls,
     fork_indexes: ForkIndexes,
     env: ResolverEnvironment,
+    current_environment: MarkerEnvironment,
     tags: Option<Tags>,
     workspace_members: BTreeSet<PackageName>,
     options: Options,
@@ -178,6 +181,7 @@ impl NoSolutionError {
         fork_urls: ForkUrls,
         fork_indexes: ForkIndexes,
         env: ResolverEnvironment,
+        current_environment: MarkerEnvironment,
         tags: Option<Tags>,
         workspace_members: BTreeSet<PackageName>,
         options: Options,
@@ -196,6 +200,7 @@ impl NoSolutionError {
             fork_urls,
             fork_indexes,
             env,
+            current_environment,
             tags,
             workspace_members,
             options,
@@ -347,6 +352,42 @@ impl NoSolutionError {
     pub fn header(&self) -> NoSolutionHeader {
         NoSolutionHeader::new(self.env.clone())
     }
+
+    /// Hint at limiting the resolver environment if universal resolution failed for a target
+    /// that is not the current platform or Python environment.
+    fn hint_disjoint_targets(&self, f: &mut Formatter) -> std::fmt::Result {
+        // Only applicable to universal resolution.
+        let Some(markers) = self.env.fork_markers() else {
+            return Ok(());
+        };
+
+        // TODO(konsti): This is a crude approximation to telling the user the difference
+        // between their Python version and the relevant Python version range from the marker.
+        let current_python_version = MarkerTree::expression(MarkerExpression::Version {
+            key: MarkerValueVersion::PythonVersion,
+            specifier: VersionSpecifier::equals_version(
+                self.current_environment.python_version().version.clone(),
+            ),
+        });
+        if markers.is_disjoint(current_python_version) {
+            write!(
+                    f,
+                    "\n\n{}{} The resolution failed for a Python version range different than the current Python version, \
+                    consider limiting the Python version range using `requires-python`.",
+                    "hint".bold().cyan(),
+                    ":".bold(),
+                )?;
+        } else if !markers.evaluate(&self.current_environment, &[]) {
+            write!(
+                f,
+                "\n\n{}{} The resolution failed for an environment that is not the current one, \
+                    consider limiting the environments with `tool.uv.environments`.",
+                "hint".bold().cyan(),
+                ":".bold(),
+            )?;
+        }
+        Ok(())
+    }
 }
 
 impl std::fmt::Debug for NoSolutionError {
@@ -366,6 +407,7 @@ impl std::fmt::Debug for NoSolutionError {
             fork_urls,
             fork_indexes,
             env,
+            current_environment,
             tags,
             workspace_members,
             options,
@@ -383,6 +425,7 @@ impl std::fmt::Debug for NoSolutionError {
             .field("fork_urls", fork_urls)
             .field("fork_indexes", fork_indexes)
             .field("env", env)
+            .field("current_environment", current_environment)
             .field("tags", tags)
             .field("workspace_members", workspace_members)
             .field("options", options)
@@ -446,6 +489,7 @@ impl std::fmt::Display for NoSolutionError {
 
         // Include any additional hints.
         let mut additional_hints = IndexSet::default();
+
         formatter.generate_hints(
             &tree,
             &self.index,
@@ -467,6 +511,8 @@ impl std::fmt::Display for NoSolutionError {
             write!(f, "\n\n{hint}")?;
         }
 
+        self.hint_disjoint_targets(f)?;
+
         Ok(())
     }
 }

crates/uv-resolver/src/resolver/environment.rs

@@ -198,6 +198,14 @@ impl ResolverEnvironment {
         crate::marker::requires_python(pep508_marker)
     }
 
+    /// For a universal resolution, return the markers of the current fork.
+    pub(crate) fn fork_markers(&self) -> Option<MarkerTree> {
+        match self.kind {
+            Kind::Specific { .. } => None,
+            Kind::Universal { markers, .. } => Some(markers),
+        }
+    }
+
     /// Narrow this environment given the forking markers.
     ///
     /// This effectively intersects any markers in this environment with the

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

@@ -31,7 +31,9 @@ use uv_distribution_types::{
 use uv_git::GitResolver;
 use uv_normalize::{ExtraName, GroupName, PackageName};
 use uv_pep440::{release_specifiers_to_ranges, Version, VersionSpecifiers, MIN_VERSION};
-use uv_pep508::{MarkerExpression, MarkerOperator, MarkerTree, MarkerValueString};
+use uv_pep508::{
+    MarkerEnvironment, MarkerExpression, MarkerOperator, MarkerTree, MarkerValueString,
+};
 use uv_platform_tags::Tags;
 use uv_pypi_types::{ConflictItem, ConflictItemRef, Conflicts, VerbatimParsedUrl};
 use uv_types::{BuildContext, HashStrategy, InstalledPackagesProvider};
@@ -115,6 +117,8 @@ struct ResolverState<InstalledPackages: InstalledPackagesProvider> {
     dependency_mode: DependencyMode,
     hasher: HashStrategy,
     env: ResolverEnvironment,
+    // The environment of the current Python interpreter.
+    current_environment: MarkerEnvironment,
     tags: Option<Tags>,
     python_requirement: PythonRequirement,
     conflicts: Conflicts,
@@ -158,6 +162,7 @@ impl<'a, Context: BuildContext, InstalledPackages: InstalledPackagesProvider>
         options: Options,
         python_requirement: &'a PythonRequirement,
         env: ResolverEnvironment,
+        current_environment: &MarkerEnvironment,
         conflicts: Conflicts,
         tags: Option<&'a Tags>,
         flat_index: &'a FlatIndex,
@@ -184,6 +189,7 @@ impl<'a, Context: BuildContext, InstalledPackages: InstalledPackagesProvider>
             options,
             hasher,
             env,
+            current_environment,
             tags.cloned(),
             python_requirement,
             conflicts,
@@ -206,6 +212,7 @@ impl<Provider: ResolverProvider, InstalledPackages: InstalledPackagesProvider>
         options: Options,
         hasher: &HashStrategy,
         env: ResolverEnvironment,
+        current_environment: &MarkerEnvironment,
         tags: Option<Tags>,
         python_requirement: &PythonRequirement,
         conflicts: Conflicts,
@@ -234,6 +241,7 @@ impl<Provider: ResolverProvider, InstalledPackages: InstalledPackagesProvider>
             hasher: hasher.clone(),
             locations: locations.clone(),
             env,
+            current_environment: current_environment.clone(),
             tags,
             python_requirement: python_requirement.clone(),
             conflicts,
@@ -354,6 +362,7 @@ impl<InstalledPackages: InstalledPackagesProvider> ResolverState<InstalledPackag
                                     state.fork_urls,
                                     state.fork_indexes,
                                     state.env,
+                                    self.current_environment.clone(),
                                     &visited,
                                 ));
                             }
@@ -2502,6 +2511,7 @@ impl<InstalledPackages: InstalledPackagesProvider> ResolverState<InstalledPackag
         fork_urls: ForkUrls,
         fork_indexes: ForkIndexes,
         env: ResolverEnvironment,
+        current_environment: MarkerEnvironment,
         visited: &FxHashSet<PackageName>,
     ) -> ResolveError {
         err = NoSolutionError::collapse_local_version_segments(NoSolutionError::collapse_proxies(
@@ -2587,6 +2597,7 @@ impl<InstalledPackages: InstalledPackagesProvider> ResolverState<InstalledPackag
             fork_urls,
             fork_indexes,
             env,
+            current_environment,
             self.tags.clone(),
             self.workspace_members.clone(),
             self.options.clone(),

crates/uv/src/commands/pip/compile.rs

@@ -517,6 +517,7 @@ pub(crate) async fn pip_compile(
         tags.as_deref(),
         resolver_env.clone(),
         python_requirement,
+        interpreter.markers(),
         Conflicts::empty(),
         &client,
         &flat_index,

crates/uv/src/commands/pip/install.rs

@@ -478,6 +478,7 @@ pub(crate) async fn pip_install(
             Some(&tags),
             ResolverEnvironment::specific(marker_env.clone()),
             python_requirement,
+            interpreter.markers(),
             Conflicts::empty(),
             &client,
             &flat_index,

crates/uv/src/commands/pip/operations.rs

@@ -29,6 +29,7 @@ use uv_fs::Simplified;
 use uv_install_wheel::LinkMode;
 use uv_installer::{Plan, Planner, Preparer, SitePackages};
 use uv_normalize::{GroupName, PackageName};
+use uv_pep508::MarkerEnvironment;
 use uv_platform_tags::Tags;
 use uv_pypi_types::{Conflicts, ResolverMarkerEnvironment};
 use uv_python::{PythonEnvironment, PythonInstallation};
@@ -119,6 +120,7 @@ pub(crate) async fn resolve<InstalledPackages: InstalledPackagesProvider>(
     tags: Option<&Tags>,
     resolver_env: ResolverEnvironment,
     python_requirement: PythonRequirement,
+    current_environment: &MarkerEnvironment,
     conflicts: Conflicts,
     client: &RegistryClient,
     flat_index: &FlatIndex,
@@ -303,6 +305,7 @@ pub(crate) async fn resolve<InstalledPackages: InstalledPackagesProvider>(
             options,
             &python_requirement,
             resolver_env,
+            current_environment,
             conflicts,
             tags,
             flat_index,

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

@@ -411,6 +411,7 @@ pub(crate) async fn pip_sync(
             Some(&tags),
             ResolverEnvironment::specific(marker_env.clone()),
             python_requirement,
+            interpreter.markers(),
             Conflicts::empty(),
             &client,
             &flat_index,

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

@@ -817,6 +817,7 @@ async fn do_lock(
                 None,
                 resolver_env,
                 python_requirement,
+                interpreter.markers(),
                 conflicts.clone(),
                 &client,
                 &flat_index,