Add support for configuring the `python-preference` with `UV_PYTHON_PREFERENCE` (#6432)

Part of https://github.com/astral-sh/uv/issues/6406

crates/uv-cli/src/lib.rs

@@ -115,7 +115,8 @@ pub struct GlobalArgs {
         global = true,
         long,
         help_heading = "Python options",
-        display_order = 700
+        display_order = 700,
+        env = "UV_PYTHON_PREFERENCE"
     )]
     pub python_preference: Option<PythonPreference>,
 

crates/uv/tests/help.rs

@@ -39,8 +39,8 @@ fn help() {
 
     Python options:
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer uv-managed or system Python installations [possible values:
-              only-managed, managed, system, only-system]
+              Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
+              [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
               Disable automatic downloads of Python
 
@@ -101,8 +101,8 @@ fn help_flag() {
 
     Python options:
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer uv-managed or system Python installations [possible values:
-              only-managed, managed, system, only-system]
+              Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
+              [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
               Disable automatic downloads of Python
 
@@ -162,8 +162,8 @@ fn help_short_flag() {
 
     Python options:
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer uv-managed or system Python installations [possible values:
-              only-managed, managed, system, only-system]
+              Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
+              [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
               Disable automatic downloads of Python
 
@@ -269,6 +269,8 @@ fn help_subcommand() {
               By default, uv prefers using Python versions it manages. However, it will use system
               Python installations if a uv-managed Python is not installed. This option allows
               prioritizing or ignoring system Python installations.
+              
+              [env: UV_PYTHON_PREFERENCE=]
 
               Possible values:
               - only-managed: Only use managed Python installations; never use system Python
@@ -416,6 +418,8 @@ fn help_subsubcommand() {
               By default, uv prefers using Python versions it manages. However, it will use system
               Python installations if a uv-managed Python is not installed. This option allows
               prioritizing or ignoring system Python installations.
+              
+              [env: UV_PYTHON_PREFERENCE=]
 
               Possible values:
               - only-managed: Only use managed Python installations; never use system Python
@@ -526,8 +530,8 @@ fn help_flag_subcommand() {
 
     Python options:
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer uv-managed or system Python installations [possible values:
-              only-managed, managed, system, only-system]
+              Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
+              [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
               Disable automatic downloads of Python
 
@@ -578,8 +582,8 @@ fn help_flag_subsubcommand() {
 
     Python options:
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer uv-managed or system Python installations [possible values:
-              only-managed, managed, system, only-system]
+              Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
+              [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
               Disable automatic downloads of Python
 
@@ -710,8 +714,8 @@ fn help_with_global_option() {
 
     Python options:
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer uv-managed or system Python installations [possible values:
-              only-managed, managed, system, only-system]
+              Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
+              [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
               Disable automatic downloads of Python
 
@@ -809,8 +813,8 @@ fn help_with_no_pager() {
 
     Python options:
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer uv-managed or system Python installations [possible values:
-              only-managed, managed, system, only-system]
+              Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
+              [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
               Disable automatic downloads of Python
 

docs/configuration/environment.md

@@ -56,6 +56,8 @@ uv accepts the following command-line arguments as environment variables:
   directories.
 - `UV_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will
   exclude distributions published after the specified date.
+- `UV_PYTHON_PREFERENCE`: Equivalent to the `--python-preference` command-line argument. Whether uv
+  should prefer system or managed Python versions.
 
 In each case, the corresponding command-line argument takes precedence over an environment variable.