Improve CLI documentation for global options (#5834)

Slowly auditing our CLI help text

crates/uv-cli/src/lib.rs

@@ -74,6 +74,9 @@ pub struct Cli {
     pub global_args: Box<GlobalArgs>,
 
     /// The path to a `uv.toml` file to use for configuration.
+    ///
+    /// While uv configuration can be included in a `pyproject.toml` file, it is
+    /// not allowed in this context.
     #[arg(
         global = true,
         long,
@@ -82,17 +85,18 @@ pub struct Cli {
     )]
     pub config_file: Option<PathBuf>,
 
-    /// Avoid discovering configuration files (`pyproject.toml`, `uv.toml`) in the current directory,
+    /// Avoid discovering configuration files (`pyproject.toml`, `uv.toml`).
+    ///
+    /// Normally, configuration files are discovered in the current directory,
     /// parent directories, or user configuration directories.
     #[arg(global = true, long, env = "UV_NO_CONFIG", value_parser = clap::builder::BoolishValueParser::new(), help_heading = "Global options")]
     pub no_config: bool,
 
-    /// Print help.
+    /// Display the concise help for this command.
     #[arg(global = true, short, long, action = clap::ArgAction::HelpShort, help_heading = "Global options")]
     help: Option<bool>,
 
-    /// Print version.
-    // This enable it to show under Global options section.
+    /// Display the uv version.
     #[arg(global = true, short = 'V', long, action = clap::ArgAction::Version, help_heading = "Global options")]
     version: Option<bool>,
 }
@@ -101,8 +105,12 @@ pub struct Cli {
 #[command(next_help_heading = "Global options", next_display_order = 1000)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct GlobalArgs {
-    /// Whether to prefer using Python installations that are already present on the system, or
-    /// those that are downloaded and installed by uv.
+    /// Whether to prefer uv-managed or system Python installations.
+    ///
+    /// 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.
     #[arg(
         global = true,
         long,
@@ -126,7 +134,9 @@ pub struct GlobalArgs {
     #[arg(global = true, action = clap::ArgAction::Count, long, short, conflicts_with = "quiet")]
     pub verbose: u8,
 
-    /// Disable colors; provided for compatibility with `pip`.
+    /// Disable colors.
+    ///
+    /// Provided for compatibility with `pip`, use `--color` instead.
     #[arg(global = true, long, hide = true, conflicts_with = "color")]
     pub no_color: bool,
 
@@ -156,7 +166,9 @@ pub struct GlobalArgs {
     #[arg(global = true, long, overrides_with("native_tls"), hide = true)]
     pub no_native_tls: bool,
 
-    /// Disable network access, relying only on locally cached data and locally available files.
+    /// Disable network access.
+    ///
+    /// When disabled, uv will only use locally cached data and locally available files.
     #[arg(global = true, long, overrides_with("no_offline"))]
     pub offline: bool,
 
@@ -164,22 +176,32 @@ pub struct GlobalArgs {
     pub no_offline: bool,
 
     /// Whether to enable experimental, preview features.
+    ///
+    /// Preview features may change without warning.
     #[arg(global = true, long, hide = true, env = "UV_PREVIEW", value_parser = clap::builder::BoolishValueParser::new(), overrides_with("no_preview"))]
     pub preview: bool,
 
     #[arg(global = true, long, overrides_with("preview"), hide = true)]
     pub no_preview: bool,
 
-    /// Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-    /// parent directories.
+    /// Avoid discovering a `pyproject.toml` or `uv.toml` file.
+    ///
+    /// Normally, configuration files are discovered in the current directory,
+    /// parent directories, or user configuration directories.
+    ///
+    /// This option is deprecated in favor of `--no-config`.
     #[arg(global = true, long, hide = true)]
     pub isolated: bool,
 
     /// Show the resolved settings for the current command.
+    ///
+    /// This option is used for debugging and development purposes.
     #[arg(global = true, long, hide = true)]
     pub show_settings: bool,
 
-    /// Hides all progress outputs when set
+    /// Hide all progress outputs.
+    ///
+    /// For example, spinners or progress bars.
     #[arg(global = true, long)]
     pub no_progress: bool,
 

crates/uv/tests/help.rs

@@ -38,9 +38,8 @@ fn help() {
 
     Python options:
           --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, managed,
-              system, only-system]
+              Whether to prefer uv-managed or system Python installations [possible values:
+              only-managed, managed, system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -52,16 +51,14 @@ fn help() {
                                        always, never]
           --native-tls                 Whether to load TLS certificates from the platform's native
                                        certificate store [env: UV_NATIVE_TLS=]
-          --offline                    Disable network access, relying only on locally cached data and
-                                       locally available files
-          --no-progress                Hides all progress outputs when set
+          --offline                    Disable network access
+          --no-progress                Hide all progress outputs
           --config-file <CONFIG_FILE>  The path to a `uv.toml` file to use for configuration [env:
                                        UV_CONFIG_FILE=]
           --no-config                  Avoid discovering configuration files (`pyproject.toml`,
-                                       `uv.toml`) in the current directory, parent directories, or user
-                                       configuration directories [env: UV_NO_CONFIG=]
-      -h, --help                       Print help
-      -V, --version                    Print version
+                                       `uv.toml`) [env: UV_NO_CONFIG=]
+      -h, --help                       Display the concise help for this command
+      -V, --version                    Display the uv version
 
     Use `uv help <command>` for more information on a specific command.
 
@@ -104,9 +101,8 @@ fn help_flag() {
 
     Python options:
           --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, managed,
-              system, only-system]
+              Whether to prefer uv-managed or system Python installations [possible values:
+              only-managed, managed, system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -118,16 +114,14 @@ fn help_flag() {
                                        always, never]
           --native-tls                 Whether to load TLS certificates from the platform's native
                                        certificate store [env: UV_NATIVE_TLS=]
-          --offline                    Disable network access, relying only on locally cached data and
-                                       locally available files
-          --no-progress                Hides all progress outputs when set
+          --offline                    Disable network access
+          --no-progress                Hide all progress outputs
           --config-file <CONFIG_FILE>  The path to a `uv.toml` file to use for configuration [env:
                                        UV_CONFIG_FILE=]
           --no-config                  Avoid discovering configuration files (`pyproject.toml`,
-                                       `uv.toml`) in the current directory, parent directories, or user
-                                       configuration directories [env: UV_NO_CONFIG=]
-      -h, --help                       Print help
-      -V, --version                    Print version
+                                       `uv.toml`) [env: UV_NO_CONFIG=]
+      -h, --help                       Display the concise help for this command
+      -V, --version                    Display the uv version
 
     Use `uv help` for more details.
 
@@ -169,9 +163,8 @@ fn help_short_flag() {
 
     Python options:
           --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, managed,
-              system, only-system]
+              Whether to prefer uv-managed or system Python installations [possible values:
+              only-managed, managed, system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -183,16 +176,14 @@ fn help_short_flag() {
                                        always, never]
           --native-tls                 Whether to load TLS certificates from the platform's native
                                        certificate store [env: UV_NATIVE_TLS=]
-          --offline                    Disable network access, relying only on locally cached data and
-                                       locally available files
-          --no-progress                Hides all progress outputs when set
+          --offline                    Disable network access
+          --no-progress                Hide all progress outputs
           --config-file <CONFIG_FILE>  The path to a `uv.toml` file to use for configuration [env:
                                        UV_CONFIG_FILE=]
           --no-config                  Avoid discovering configuration files (`pyproject.toml`,
-                                       `uv.toml`) in the current directory, parent directories, or user
-                                       configuration directories [env: UV_NO_CONFIG=]
-      -h, --help                       Print help
-      -V, --version                    Print version
+                                       `uv.toml`) [env: UV_NO_CONFIG=]
+      -h, --help                       Display the concise help for this command
+      -V, --version                    Display the uv version
 
     Use `uv help` for more details.
 
@@ -237,8 +228,11 @@ fn help_subcommand() {
 
     Python options:
           --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
+              Whether to prefer uv-managed or system Python installations.
+              
+              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.
 
               Possible values:
               - only-managed: Only use managed Python installations; never use system Python
@@ -291,27 +285,36 @@ fn help_subcommand() {
               [env: UV_NATIVE_TLS=]
 
           --offline
-              Disable network access, relying only on locally cached data and locally available files
+              Disable network access.
+              
+              When disabled, uv will only use locally cached data and locally available files.
 
           --no-progress
-              Hides all progress outputs when set
+              Hide all progress outputs.
+              
+              For example, spinners or progress bars.
 
           --config-file <CONFIG_FILE>
-              The path to a `uv.toml` file to use for configuration
+              The path to a `uv.toml` file to use for configuration.
+              
+              While uv configuration can be included in a `pyproject.toml` file, it is not allowed in
+              this context.
               
               [env: UV_CONFIG_FILE=]
 
           --no-config
-              Avoid discovering configuration files (`pyproject.toml`, `uv.toml`) in the current
-              directory, parent directories, or user configuration directories
+              Avoid discovering configuration files (`pyproject.toml`, `uv.toml`).
+              
+              Normally, configuration files are discovered in the current directory, parent directories,
+              or user configuration directories.
               
               [env: UV_NO_CONFIG=]
 
       -h, --help
-              Print help
+              Display the concise help for this command
 
       -V, --version
-              Print version
+              Display the uv version
 
     Use `uv help python <command>` for more information on a specific command.
 
@@ -361,8 +364,11 @@ fn help_subsubcommand() {
 
     Python options:
           --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
+              Whether to prefer uv-managed or system Python installations.
+              
+              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.
 
               Possible values:
               - only-managed: Only use managed Python installations; never use system Python
@@ -415,27 +421,36 @@ fn help_subsubcommand() {
               [env: UV_NATIVE_TLS=]
 
           --offline
-              Disable network access, relying only on locally cached data and locally available files
+              Disable network access.
+              
+              When disabled, uv will only use locally cached data and locally available files.
 
           --no-progress
-              Hides all progress outputs when set
+              Hide all progress outputs.
+              
+              For example, spinners or progress bars.
 
           --config-file <CONFIG_FILE>
-              The path to a `uv.toml` file to use for configuration
+              The path to a `uv.toml` file to use for configuration.
+              
+              While uv configuration can be included in a `pyproject.toml` file, it is not allowed in
+              this context.
               
               [env: UV_CONFIG_FILE=]
 
           --no-config
-              Avoid discovering configuration files (`pyproject.toml`, `uv.toml`) in the current
-              directory, parent directories, or user configuration directories
+              Avoid discovering configuration files (`pyproject.toml`, `uv.toml`).
+              
+              Normally, configuration files are discovered in the current directory, parent directories,
+              or user configuration directories.
               
               [env: UV_NO_CONFIG=]
 
       -h, --help
-              Print help
+              Display the concise help for this command
 
       -V, --version
-              Print version
+              Display the uv version
 
 
     ----- stderr -----
@@ -469,9 +484,8 @@ fn help_flag_subcommand() {
 
     Python options:
           --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, managed,
-              system, only-system]
+              Whether to prefer uv-managed or system Python installations [possible values:
+              only-managed, managed, system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -483,16 +497,14 @@ fn help_flag_subcommand() {
                                        always, never]
           --native-tls                 Whether to load TLS certificates from the platform's native
                                        certificate store [env: UV_NATIVE_TLS=]
-          --offline                    Disable network access, relying only on locally cached data and
-                                       locally available files
-          --no-progress                Hides all progress outputs when set
+          --offline                    Disable network access
+          --no-progress                Hide all progress outputs
           --config-file <CONFIG_FILE>  The path to a `uv.toml` file to use for configuration [env:
                                        UV_CONFIG_FILE=]
           --no-config                  Avoid discovering configuration files (`pyproject.toml`,
-                                       `uv.toml`) in the current directory, parent directories, or user
-                                       configuration directories [env: UV_NO_CONFIG=]
-      -h, --help                       Print help
-      -V, --version                    Print version
+                                       `uv.toml`) [env: UV_NO_CONFIG=]
+      -h, --help                       Display the concise help for this command
+      -V, --version                    Display the uv version
 
     Use `uv help python` for more details.
 
@@ -525,9 +537,8 @@ fn help_flag_subsubcommand() {
 
     Python options:
           --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, managed,
-              system, only-system]
+              Whether to prefer uv-managed or system Python installations [possible values:
+              only-managed, managed, system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -539,16 +550,14 @@ fn help_flag_subsubcommand() {
                                        always, never]
           --native-tls                 Whether to load TLS certificates from the platform's native
                                        certificate store [env: UV_NATIVE_TLS=]
-          --offline                    Disable network access, relying only on locally cached data and
-                                       locally available files
-          --no-progress                Hides all progress outputs when set
+          --offline                    Disable network access
+          --no-progress                Hide all progress outputs
           --config-file <CONFIG_FILE>  The path to a `uv.toml` file to use for configuration [env:
                                        UV_CONFIG_FILE=]
           --no-config                  Avoid discovering configuration files (`pyproject.toml`,
-                                       `uv.toml`) in the current directory, parent directories, or user
-                                       configuration directories [env: UV_NO_CONFIG=]
-      -h, --help                       Print help
-      -V, --version                    Print version
+                                       `uv.toml`) [env: UV_NO_CONFIG=]
+      -h, --help                       Display the concise help for this command
+      -V, --version                    Display the uv version
 
     ----- stderr -----
     "###);
@@ -658,9 +667,8 @@ fn help_with_global_option() {
 
     Python options:
           --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, managed,
-              system, only-system]
+              Whether to prefer uv-managed or system Python installations [possible values:
+              only-managed, managed, system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -672,16 +680,14 @@ fn help_with_global_option() {
                                        always, never]
           --native-tls                 Whether to load TLS certificates from the platform's native
                                        certificate store [env: UV_NATIVE_TLS=]
-          --offline                    Disable network access, relying only on locally cached data and
-                                       locally available files
-          --no-progress                Hides all progress outputs when set
+          --offline                    Disable network access
+          --no-progress                Hide all progress outputs
           --config-file <CONFIG_FILE>  The path to a `uv.toml` file to use for configuration [env:
                                        UV_CONFIG_FILE=]
           --no-config                  Avoid discovering configuration files (`pyproject.toml`,
-                                       `uv.toml`) in the current directory, parent directories, or user
-                                       configuration directories [env: UV_NO_CONFIG=]
-      -h, --help                       Print help
-      -V, --version                    Print version
+                                       `uv.toml`) [env: UV_NO_CONFIG=]
+      -h, --help                       Display the concise help for this command
+      -V, --version                    Display the uv version
 
     Use `uv help <command>` for more information on a specific command.
 
@@ -760,9 +766,8 @@ fn help_with_no_pager() {
 
     Python options:
           --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, managed,
-              system, only-system]
+              Whether to prefer uv-managed or system Python installations [possible values:
+              only-managed, managed, system, only-system]
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
@@ -774,16 +779,14 @@ fn help_with_no_pager() {
                                        always, never]
           --native-tls                 Whether to load TLS certificates from the platform's native
                                        certificate store [env: UV_NATIVE_TLS=]
-          --offline                    Disable network access, relying only on locally cached data and
-                                       locally available files
-          --no-progress                Hides all progress outputs when set
+          --offline                    Disable network access
+          --no-progress                Hide all progress outputs
           --config-file <CONFIG_FILE>  The path to a `uv.toml` file to use for configuration [env:
                                        UV_CONFIG_FILE=]
           --no-config                  Avoid discovering configuration files (`pyproject.toml`,
-                                       `uv.toml`) in the current directory, parent directories, or user
-                                       configuration directories [env: UV_NO_CONFIG=]
-      -h, --help                       Print help
-      -V, --version                    Print version
+                                       `uv.toml`) [env: UV_NO_CONFIG=]
+      -h, --help                       Display the concise help for this command
+      -V, --version                    Display the uv version
 
     Use `uv help <command>` for more information on a specific command.
 

docs/reference/cli.md

@@ -189,7 +189,9 @@ uv run [OPTIONS] <COMMAND>
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -223,7 +225,9 @@ uv run [OPTIONS] <COMMAND>
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -265,7 +269,9 @@ uv init [OPTIONS] [PATH]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -299,7 +305,9 @@ uv init [OPTIONS] [PATH]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -456,7 +464,9 @@ uv add [OPTIONS] <REQUIREMENTS>...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -490,7 +500,9 @@ uv add [OPTIONS] <REQUIREMENTS>...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -639,7 +651,9 @@ uv remove [OPTIONS] <REQUIREMENTS>...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -673,7 +687,9 @@ uv remove [OPTIONS] <REQUIREMENTS>...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -818,7 +834,9 @@ uv sync [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -852,7 +870,9 @@ uv sync [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -991,7 +1011,9 @@ uv lock [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1025,7 +1047,9 @@ uv lock [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1210,7 +1234,9 @@ uv tree [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1244,7 +1270,9 @@ uv tree [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1417,7 +1445,9 @@ uv tool run [OPTIONS] [COMMAND]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1451,7 +1481,9 @@ uv tool run [OPTIONS] [COMMAND]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1600,7 +1632,9 @@ uv tool install [OPTIONS] <PACKAGE>
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1634,7 +1668,9 @@ uv tool install [OPTIONS] <PACKAGE>
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1654,7 +1690,9 @@ uv tool list [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1688,7 +1726,9 @@ uv tool list [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1714,7 +1754,9 @@ uv tool uninstall [OPTIONS] <NAME>
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1748,7 +1790,9 @@ uv tool uninstall [OPTIONS] <NAME>
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1768,7 +1812,9 @@ uv tool update-shell [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1802,7 +1848,9 @@ uv tool update-shell [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1822,7 +1870,9 @@ uv tool dir [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1856,7 +1906,9 @@ uv tool dir [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1902,7 +1954,9 @@ uv python list [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1936,7 +1990,9 @@ uv python list [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -1964,7 +2020,9 @@ uv python install [OPTIONS] [TARGETS]...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -1998,7 +2056,9 @@ uv python install [OPTIONS] [TARGETS]...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -2024,7 +2084,9 @@ uv python find [OPTIONS] [REQUEST]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -2058,7 +2120,9 @@ uv python find [OPTIONS] [REQUEST]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -2084,7 +2148,9 @@ uv python pin [OPTIONS] [REQUEST]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -2118,7 +2184,9 @@ uv python pin [OPTIONS] [REQUEST]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -2138,7 +2206,9 @@ uv python dir [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -2172,7 +2242,9 @@ uv python dir [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -2198,7 +2270,9 @@ uv python uninstall [OPTIONS] <TARGETS>...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -2232,7 +2306,9 @@ uv python uninstall [OPTIONS] <TARGETS>...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -2505,7 +2581,9 @@ uv pip compile [OPTIONS] <SRC_FILE>...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -2539,7 +2617,9 @@ uv pip compile [OPTIONS] <SRC_FILE>...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -2725,7 +2805,9 @@ uv pip sync [OPTIONS] <SRC_FILE>...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -2759,7 +2841,9 @@ uv pip sync [OPTIONS] <SRC_FILE>...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -2991,7 +3075,9 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3025,7 +3111,9 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3084,7 +3172,9 @@ uv pip uninstall [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>>
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3118,7 +3208,9 @@ uv pip uninstall [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>>
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3152,7 +3244,9 @@ uv pip freeze [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3186,7 +3280,9 @@ uv pip freeze [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3234,7 +3330,9 @@ uv pip list [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3268,7 +3366,9 @@ uv pip list [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3308,7 +3408,9 @@ uv pip show [OPTIONS] [PACKAGE]...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3342,7 +3444,9 @@ uv pip show [OPTIONS] [PACKAGE]...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3383,7 +3487,9 @@ uv pip tree [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3417,7 +3523,9 @@ uv pip tree [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3451,7 +3559,9 @@ uv pip check [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3485,7 +3595,9 @@ uv pip check [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3608,7 +3720,9 @@ uv venv [OPTIONS] [NAME]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3642,7 +3756,9 @@ uv venv [OPTIONS] [NAME]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3688,7 +3804,9 @@ uv cache clean [OPTIONS] [PACKAGE]...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3722,7 +3840,9 @@ uv cache clean [OPTIONS] [PACKAGE]...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3742,7 +3862,9 @@ uv cache prune [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3776,7 +3898,9 @@ uv cache prune [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3796,7 +3920,9 @@ uv cache dir [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3830,7 +3956,9 @@ uv cache dir [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3850,7 +3978,9 @@ uv version [OPTIONS]
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3884,7 +4014,9 @@ uv version [OPTIONS]
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>
 
@@ -3908,7 +4040,9 @@ uv help [OPTIONS] [COMMAND]...
 
 <p>Defaults to <code>$HOME/Library/Caches/uv</code> on macOS, <code>$XDG_CACHE_HOME/uv</code> or <code>$HOME/.cache/uv</code> on Linux, and <code>{FOLDERID_LocalAppData}\uv\cache</code> on Windows.</p>
 
-</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv</p>
+</dd><dt><code>--python-preference</code> <i>python-preference</i></dt><dd><p>Whether to prefer uv-managed or system Python installations.</p>
+
+<p>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.</p>
 
 <p>Possible values:</p>
 
@@ -3942,7 +4076,9 @@ uv help [OPTIONS] [COMMAND]...
 
 <li><code>never</code>:  Disables colored output</li>
 </ul>
-</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration</p>
+</dd><dt><code>--config-file</code> <i>config-file</i></dt><dd><p>The path to a <code>uv.toml</code> file to use for configuration.</p>
+
+<p>While uv configuration can be included in a <code>pyproject.toml</code> file, it is not allowed in this context.</p>
 
 </dd></dl>