Replace `--python-preference installed` with `managed` (#5637)

Collapses the previous default into "managed" and makes the "managed"
behavior match "installed". People should use "only-managed" if they
want that behavior, it seems overly complicated otherwise.

crates/uv-python/src/discovery.rs

@@ -61,12 +61,11 @@ pub enum PythonRequest {
 pub enum PythonPreference {
     /// Only use managed Python installations; never use system Python installations.
     OnlyManaged,
-    /// Prefer installed Python installations, only download managed Python installations if no system Python installation is found.
-    ///
-    /// Installed managed Python installations are still preferred over system Python installations.
     #[default]
-    Installed,
+    /// Prefer managed Python installations over system Python installations.
-    /// Prefer managed Python installations over system Python installations, even if fetching is required.
+    ///
+    /// System Python installations are still preferred over downloading managed Python versions.
+    /// Use `only-managed` to always fetch a managed Python version.
     Managed,
     /// Prefer system Python installations over managed Python installations.
     ///
@@ -305,7 +304,7 @@ fn python_executables_from_installed<'a>(
 
     match preference {
         PythonPreference::OnlyManaged => Box::new(from_managed_installations),
-        PythonPreference::Managed | PythonPreference::Installed => Box::new(
+        PythonPreference::Managed => Box::new(
             from_managed_installations
                 .chain(from_search_path)
                 .chain(from_py_launcher),
@@ -1272,7 +1271,7 @@ impl PythonPreference {
 
         match self {
             PythonPreference::OnlyManaged => matches!(source, PythonSource::Managed),
-            Self::Managed | Self::System | Self::Installed => matches!(
+            Self::Managed | Self::System => matches!(
                 source,
                 PythonSource::Managed | PythonSource::SearchPath | PythonSource::PyLauncher
             ),
@@ -1295,7 +1294,7 @@ impl PythonPreference {
     }
 
     pub(crate) fn allows_managed(self) -> bool {
-        matches!(self, Self::Managed | Self::OnlyManaged | Self::Installed)
+        matches!(self, Self::Managed | Self::OnlyManaged)
     }
 }
 
@@ -1603,7 +1602,7 @@ impl PythonPreference {
     fn sources(self) -> &'static [&'static str] {
         match self {
             Self::OnlyManaged => &["managed installations"],
-            Self::Managed | Self::Installed | Self::System => {
+            Self::Managed | Self::System => {
                 if cfg!(windows) {
                     &["managed installations", "system path", "`py` launcher"]
                 } else {

crates/uv-python/src/installation.rs

@@ -88,13 +88,6 @@ impl PythonInstallation {
     ) -> Result<Self, Error> {
         let request = request.unwrap_or_default();
 
-        // Perform a fetch aggressively if managed Python is preferred
-        if matches!(preference, PythonPreference::Managed) && python_fetch.is_automatic() {
-            if let Some(request) = PythonDownloadRequest::from_request(&request) {
-                return Self::fetch(request.fill(), client_builder, cache, reporter).await;
-            }
-        }
-
         // Search for the installation
         match Self::find(&request, environments, preference, cache) {
             Ok(venv) => Ok(venv),

crates/uv/tests/help.rs

@@ -38,8 +38,8 @@ fn help() {
               Disable network access, relying only on locally cached data and locally available files
           --python-preference <PYTHON_PREFERENCE>
               Whether to prefer using Python installations that are already present on the system, or
-              those that are downloaded and installed by uv [possible values: only-managed, installed,
+              those that are downloaded and installed by uv [possible values: only-managed, managed,
-              managed, system, only-system]
+              system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -101,8 +101,8 @@ fn help_flag() {
               Disable network access, relying only on locally cached data and locally available files
           --python-preference <PYTHON_PREFERENCE>
               Whether to prefer using Python installations that are already present on the system, or
-              those that are downloaded and installed by uv [possible values: only-managed, installed,
+              those that are downloaded and installed by uv [possible values: only-managed, managed,
-              managed, system, only-system]
+              system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -163,8 +163,8 @@ fn help_short_flag() {
               Disable network access, relying only on locally cached data and locally available files
           --python-preference <PYTHON_PREFERENCE>
               Whether to prefer using Python installations that are already present on the system, or
-              those that are downloaded and installed by uv [possible values: only-managed, installed,
+              those that are downloaded and installed by uv [possible values: only-managed, managed,
-              managed, system, only-system]
+              system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -255,10 +255,7 @@ fn help_subcommand() {
               Possible values:
               - only-managed: Only use managed Python installations; never use system Python
                 installations
-              - installed:    Prefer installed Python installations, only download managed Python
+              - managed:      Prefer managed Python installations over system Python installations
-                installations if no system Python installation is found
-              - managed:      Prefer managed Python installations over system Python installations, even
-                if fetching is required
               - system:       Prefer system Python installations over managed Python installations
               - only-system:  Only use system Python installations; never use managed Python
                 installations
@@ -379,10 +376,7 @@ fn help_subsubcommand() {
               Possible values:
               - only-managed: Only use managed Python installations; never use system Python
                 installations
-              - installed:    Prefer installed Python installations, only download managed Python
+              - managed:      Prefer managed Python installations over system Python installations
-                installations if no system Python installation is found
-              - managed:      Prefer managed Python installations over system Python installations, even
-                if fetching is required
               - system:       Prefer system Python installations over managed Python installations
               - only-system:  Only use system Python installations; never use managed Python
                 installations
@@ -468,8 +462,8 @@ fn help_flag_subcommand() {
               Disable network access, relying only on locally cached data and locally available files
           --python-preference <PYTHON_PREFERENCE>
               Whether to prefer using Python installations that are already present on the system, or
-              those that are downloaded and installed by uv [possible values: only-managed, installed,
+              those that are downloaded and installed by uv [possible values: only-managed, managed,
-              managed, system, only-system]
+              system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -527,8 +521,8 @@ fn help_flag_subsubcommand() {
               Disable network access, relying only on locally cached data and locally available files
           --python-preference <PYTHON_PREFERENCE>
               Whether to prefer using Python installations that are already present on the system, or
-              those that are downloaded and installed by uv [possible values: only-managed, installed,
+              those that are downloaded and installed by uv [possible values: only-managed, managed,
-              managed, system, only-system]
+              system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -643,8 +637,8 @@ fn help_with_global_option() {
               Disable network access, relying only on locally cached data and locally available files
           --python-preference <PYTHON_PREFERENCE>
               Whether to prefer using Python installations that are already present on the system, or
-              those that are downloaded and installed by uv [possible values: only-managed, installed,
+              those that are downloaded and installed by uv [possible values: only-managed, managed,
-              managed, system, only-system]
+              system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -703,7 +697,7 @@ fn help_with_version() {
 }
 
 #[test]
-fn test_with_no_pager() {
+fn help_with_no_pager() {
     let context = TestContext::new_with_versions(&[]);
 
     // We can't really test whether the --no-pager option works with a snapshot test.
@@ -739,8 +733,8 @@ fn test_with_no_pager() {
               Disable network access, relying only on locally cached data and locally available files
           --python-preference <PYTHON_PREFERENCE>
               Whether to prefer using Python installations that are already present on the system, or
-              those that are downloaded and installed by uv [possible values: only-managed, installed,
+              those that are downloaded and installed by uv [possible values: only-managed, managed,
-              managed, system, only-system]
+              system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]

docs/settings.md

@@ -648,8 +648,7 @@ those that are downloaded and installed by uv.
 **Possible values**:
 
 - `"only-managed"`: Only use managed Python installations; never use system Python installations
-- `"installed"`: Prefer installed Python installations, only download managed Python installations if no system Python installation is found
+- `"managed"`: Prefer managed Python installations over system Python installations
-- `"managed"`: Prefer managed Python installations over system Python installations, even if fetching is required
 - `"system"`: Prefer system Python installations over managed Python installations
 - `"only-system"`: Only use system Python installations; never use managed Python installations
 

uv.schema.json

@@ -1001,14 +1001,7 @@
           ]
         },
         {
-          "description": "Prefer installed Python installations, only download managed Python installations if no system Python installation is found.\n\nInstalled managed Python installations are still preferred over system Python installations.",
+          "description": "Prefer managed Python installations over system Python installations.\n\nSystem Python installations are still preferred over downloading managed Python versions. Use `only-managed` to always fetch a managed Python version.",
-          "type": "string",
-          "enum": [
-            "installed"
-          ]
-        },
-        {
-          "description": "Prefer managed Python installations over system Python installations, even if fetching is required.",
           "type": "string",
           "enum": [
             "managed"