Deprecate the `--isolated` flag (#5466)

## Summary

This PR deprecates the `--isolated` flag. The treatment varies across
the APIs:

- For non-preview APIs, we warn but treat it as equivalent to
`--no-config`.
- For preview APIs, we warn and ignore it, with two exceptions...
- For `tool run` and `run` specifically, we don't even warn, because we
can't differentiate the command-specific `--isolated` from the global
`--isolated`.

.github/workflows/sync-python-releases.yml

@@ -20,8 +20,8 @@ jobs:
       - uses: hynek/setup-cached-uv@v2
       - name: Sync Python Releases
         run: |
-          uv run --isolated -- fetch-download-metadata.py
+          uv run -- fetch-download-metadata.py
-          uv run --isolated -- template-download-metadata.py
+          uv run -- template-download-metadata.py
         working-directory: ./crates/uv-python
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -255,7 +255,7 @@ project-level settings appearing earlier in the merged array.
 Settings provided via environment variables take precedence over persistent configuration, and
 settings provided via the command line take precedence over both.
 
-uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any
+uv accepts a `--no-config` command-line argument which, when provided, disables the discovery of any
 persistent configuration.
 
 uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use

crates/uv-cli/src/lib.rs

@@ -154,7 +154,7 @@ pub struct GlobalArgs {
 
     /// Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
     /// parent directories.
-    #[arg(global = true, long)]
+    #[arg(global = true, long, hide = true)]
     pub isolated: bool,
 
     /// Show the resolved settings for the current command.

crates/uv-python/fetch-download-metadata.py

@@ -11,7 +11,7 @@ Generates the `download-metadata.json` file.
 
 Usage:
 
-    uv run --isolated -- crates/uv-python/fetch-download-metadata.py
+    uv run -- crates/uv-python/fetch-download-metadata.py
 
 Acknowledgements:
 

crates/uv-python/template-download-metadata.py

@@ -11,7 +11,7 @@ Generates the `downloads.inc` file from the `downloads.inc.mustache` template.
 
 Usage:
 
-    uv run --isolated -- crates/uv-python/template-download-metadata.py
+    uv run -- crates/uv-python/template-download-metadata.py
 """
 
 import argparse

crates/uv/src/lib.rs

@@ -24,6 +24,7 @@ use uv_configuration::Concurrency;
 use uv_fs::CWD;
 use uv_requirements::RequirementsSource;
 use uv_settings::{Combine, FilesystemOptions};
+use uv_warnings::warn_user;
 use uv_workspace::{DiscoveryOptions, Workspace};
 
 use crate::commands::{ExitStatus, ToolRunCommand};
@@ -67,6 +68,39 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
         std::env::set_current_dir(directory)?;
     }
 
+    // The `--isolated` argument is deprecated on preview APIs, and warns on non-preview APIs.
+    let deprecated_isolated = if cli.global_args.isolated {
+        match &*cli.command {
+            // Supports `--isolated` as its own argument, so we can't warn either way.
+            Commands::Tool(ToolNamespace {
+                command: ToolCommand::Run(_),
+            }) => false,
+
+            // Supports `--isolated` as its own argument, so we can't warn either way.
+            Commands::Project(command) if matches!(**command, ProjectCommand::Run(_)) => false,
+
+            // `--isolated` moved to `--no-workspace`.
+            Commands::Project(command) if matches!(**command, ProjectCommand::Init(_)) => {
+                warn_user!("The `--isolated` flag is deprecated and has no effect. Instead, use `--no-config` to prevent uv from discovering configuration files or `--no-workspace` to prevent uv from adding the initialized project to the containing workspace.");
+                false
+            }
+
+            // Preview APIs. Ignore `--isolated` and warn.
+            Commands::Project(_) | Commands::Tool(_) | Commands::Python(_) => {
+                warn_user!("The `--isolated` flag is deprecated and has no effect. Instead, use `--no-config` to prevent uv from discovering configuration files.");
+                false
+            }
+
+            // Non-preview APIs. Continue to support `--isolated`, but warn.
+            _ => {
+                warn_user!("The `--isolated` flag is deprecated. Instead, use `--no-config` to prevent uv from discovering configuration files.");
+                true
+            }
+        }
+    } else {
+        false
+    };
+
     // Load configuration from the filesystem, prioritizing (in order):
     // 1. The configuration file specified on the command-line.
     // 2. The configuration file in the current workspace (i.e., the `pyproject.toml` or `uv.toml`
@@ -77,7 +111,7 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
     //    search for `pyproject.toml` files, since we're not in a workspace.
     let filesystem = if let Some(config_file) = cli.config_file.as_ref() {
         Some(FilesystemOptions::from_file(config_file)?)
-    } else if cli.global_args.isolated || cli.no_config {
+    } else if deprecated_isolated || cli.no_config {
         None
     } else if let Ok(project) = Workspace::discover(&CWD, &DiscoveryOptions::default()).await {
         let project = FilesystemOptions::from_directory(project.install_path())?;
@@ -654,7 +688,7 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
                 args.python,
                 args.settings,
                 invocation_source,
-                args.isolated || globals.isolated,
+                args.isolated,
                 globals.preview,
                 globals.python_preference,
                 globals.python_fetch,
@@ -780,7 +814,7 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
                 globals.native_tls,
                 globals.connectivity,
                 globals.preview,
-                cli.no_config || globals.isolated,
+                cli.no_config,
                 printer,
             )
             .await
@@ -826,7 +860,7 @@ async fn run(cli: Cli) -> Result<ExitStatus> {
                 args.resolved,
                 globals.python_preference,
                 globals.preview,
-                args.no_workspace || globals.isolated,
+                args.no_workspace,
                 &cache,
                 printer,
             )
@@ -876,7 +910,7 @@ async fn run_project(
                 args.r#virtual,
                 args.no_readme,
                 args.python,
-                args.no_workspace || globals.isolated,
+                args.no_workspace,
                 globals.preview,
                 globals.python_preference,
                 globals.python_fetch,
@@ -916,7 +950,7 @@ async fn run_project(
                 args.frozen,
                 args.isolated,
                 args.package,
-                args.no_project || globals.isolated,
+                args.no_project,
                 args.extras,
                 args.dev,
                 args.python,

crates/uv/src/settings.rs

@@ -43,7 +43,6 @@ pub(crate) struct GlobalSettings {
     pub(crate) color: ColorChoice,
     pub(crate) native_tls: bool,
     pub(crate) connectivity: Connectivity,
-    pub(crate) isolated: bool,
     pub(crate) show_settings: bool,
     pub(crate) preview: PreviewMode,
     pub(crate) python_preference: PythonPreference,
@@ -108,7 +107,6 @@ impl GlobalSettings {
             } else {
                 Connectivity::Online
             },
-            isolated: args.isolated,
             show_settings: args.show_settings,
             preview,
             python_preference: args

crates/uv/tests/help.rs

@@ -43,9 +43,6 @@ fn help() {
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
           --no-progress
               Hides all progress outputs when set
       -n, --no-cache
@@ -109,9 +106,6 @@ fn help_flag() {
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
           --no-progress
               Hides all progress outputs when set
       -n, --no-cache
@@ -174,9 +168,6 @@ fn help_short_flag() {
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
           --no-progress
               Hides all progress outputs when set
       -n, --no-cache
@@ -280,10 +271,6 @@ fn help_subcommand() {
               - manual:    Do not automatically fetch managed Python installations; require explicit
                 installation
 
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
-
           --no-progress
               Hides all progress outputs when set
 
@@ -408,10 +395,6 @@ fn help_subsubcommand() {
               - manual:    Do not automatically fetch managed Python installations; require explicit
                 installation
 
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
-
           --no-progress
               Hides all progress outputs when set
 
@@ -490,9 +473,6 @@ fn help_flag_subcommand() {
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
           --no-progress
               Hides all progress outputs when set
       -n, --no-cache
@@ -552,9 +532,6 @@ fn help_flag_subsubcommand() {
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
           --no-progress
               Hides all progress outputs when set
       -n, --no-cache
@@ -671,9 +648,6 @@ fn help_with_global_option() {
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
           --no-progress
               Hides all progress outputs when set
       -n, --no-cache
@@ -770,9 +744,6 @@ fn test_with_no_pager() {
           --python-fetch <PYTHON_FETCH>
               Whether to automatically download Python when required [possible values: automatic,
               manual]
-          --isolated
-              Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any
-              parent directories
           --no-progress
               Hides all progress outputs when set
       -n, --no-cache

crates/uv/tests/init.rs

@@ -612,7 +612,9 @@ fn init_isolated() -> Result<()> {
     ----- stdout -----
 
     ----- stderr -----
+    warning: The `--isolated` flag is deprecated and has no effect. Instead, use `--no-config` to prevent uv from discovering configuration files or `--no-workspace` to prevent uv from adding the initialized project to the containing workspace.
     warning: `uv init` is experimental and may change without warning
+    Adding `foo` as member of workspace `[TEMP_DIR]/`
     Initialized project `foo`
     "###);
 
@@ -627,6 +629,9 @@ fn init_isolated() -> Result<()> {
         name = "project"
         version = "0.1.0"
         requires-python = ">=3.12"
+
+        [tool.uv.workspace]
+        members = ["foo"]
         "###
         );
     });

crates/uv/tests/show_settings.rs

@@ -54,7 +54,6 @@ fn resolve_uv_toml() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -188,7 +187,6 @@ fn resolve_uv_toml() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -323,7 +321,6 @@ fn resolve_uv_toml() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -490,7 +487,6 @@ fn resolve_pyproject_toml() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -626,7 +622,6 @@ fn resolve_pyproject_toml() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -748,7 +743,6 @@ fn resolve_pyproject_toml() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -907,7 +901,6 @@ fn resolve_index_url() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -1066,7 +1059,6 @@ fn resolve_index_url() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -1270,7 +1262,6 @@ fn resolve_find_links() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -1428,7 +1419,6 @@ fn resolve_top_level() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -1556,7 +1546,6 @@ fn resolve_top_level() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -1712,7 +1701,6 @@ fn resolve_top_level() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -1892,7 +1880,6 @@ fn resolve_user_configuration() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -2010,7 +1997,6 @@ fn resolve_user_configuration() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -2128,7 +2114,6 @@ fn resolve_user_configuration() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -2248,7 +2233,6 @@ fn resolve_user_configuration() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -2393,7 +2377,6 @@ fn resolve_poetry_toml() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,
@@ -2539,7 +2522,6 @@ fn resolve_both() -> anyhow::Result<()> {
         color: Auto,
         native_tls: false,
         connectivity: Online,
-        isolated: false,
         show_settings: true,
         preview: Disabled,
         python_preference: OnlySystem,

crates/uv/tests/workspace.rs

@@ -600,6 +600,14 @@ fn test_uv_run_isolate() -> Result<()> {
     ----- stdout -----
 
     ----- stderr -----
+    Resolved 8 packages in [TIME]
+    Prepared 3 packages in [TIME]
+    Installed 5 packages in [TIME]
+     + anyio==4.3.0
+     + bird-feeder==1.0.0 (from file://[TEMP_DIR]/albatross-root-workspace/packages/bird-feeder)
+     + idna==3.6
+     + seeds==1.0.0 (from file://[TEMP_DIR]/albatross-root-workspace/packages/seeds)
+     + sniffio==1.3.1
     Traceback (most recent call last):
       File "[TEMP_DIR]/albatross-root-workspace/check_installed_albatross.py", line 1, in <module>
         from albatross import fly

docs/concepts/tools.md

@@ -125,13 +125,13 @@ fail. The `--force` flag can be used to override this behavior.
 The invocation `uv tool run <name>` is nearly equivalent to:
 
 ```console
-$ uv run --isolated --with <name> -- <name>
+$ uv run --no-project --with <name> -- <name>
 ```
 
 However, there are a couple notable differences when using uv's tool interface:
 
 - The `--with` option is not needed — the required package is inferred from the command name.
 - The temporary environment is cached in a dedicated location.
-- The `--isolated` flag is not needed — tools are always run isolated from the project.
+- The `--no-project` flag is not needed — tools are always run isolated from the project.
 - If a tool is already installed, `uv tool run` will use the installed version but `uv run` will
   not.

docs/configuration/files.md

@@ -37,7 +37,7 @@ project-level settings appearing earlier in the merged array.
 Settings provided via environment variables take precedence over persistent configuration, and
 settings provided via the command line take precedence over both.
 
-uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any
+uv accepts a `--no-config` command-line argument which, when provided, disables the discovery of any
 persistent configuration.
 
 uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use

docs/guides/scripts.md

@@ -50,11 +50,11 @@ hello world!
 
 Note that if you use `uv run` in a _project_, i.e. a directory with a `pyproject.toml`, it will
 install the current project before running the script. If your script does not depend on the
-project, use the `--isolated` flag to skip this:
+project, use the `--no-project` flag to skip this:
 
 ```console
 # Note, it is important that the flag comes _before_ the script
-$ uv run --isolated example.py
+$ uv run --no-project example.py
 ```
 
 See the [projects guide](./projects.md) for more details on working in projects.
@@ -81,7 +81,7 @@ for i in track(range(20), description="For example:"):
 If executed without specifying a dependency, this script will fail:
 
 ```console
-$ uv run --isolated example.py
+$ uv run --no-project example.py
 Traceback (most recent call last):
   File "/Users/astral/example.py", line 2, in <module>
     from rich.progress import track
@@ -104,7 +104,7 @@ $ uv run --with 'rich>12,<13' example.py
 Multiple dependencies can be requested by repeating with `--with` option.
 
 Note that if `uv run` is used in a _project_, these dependencies will be included _in addition_ to
-the project's dependencies. To opt-out of this behavior, use the `--isolated` flag.
+the project's dependencies. To opt-out of this behavior, use the `--no-project` flag.
 
 ## Declaring script dependencies
 
@@ -167,7 +167,7 @@ versions](../concepts/python-versions.md) for more details. Note that the `depen
 be provided even if empty.
 
 Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's
-dependencies will be ignored. The `--isolated` flag is not required.
+dependencies will be ignored. The `--no-project` flag is not required.
 
 ## Using different Python versions
 

scripts/release.sh

@@ -11,14 +11,14 @@ echo "Updating metadata with rooster..."
 cd "$project_root"
 
 # Update the preview changelog
-uv tool run --from 'rooster-blue>=0.0.7' --python 3.12 --isolated -- \
+uv tool run --from 'rooster-blue>=0.0.7' --python 3.12 -- \
     rooster release "$@" \
     --only-sections preview \
     --changelog-file PREVIEW-CHANGELOG.md \
     --no-update-pyproject --no-update-version-files
 
 # Update the real changelog
-uv tool run --from 'rooster-blue>=0.0.7' --python 3.12 --isolated -- \
+uv tool run --from 'rooster-blue>=0.0.7' --python 3.12 -- \
     rooster release "$@" --without-sections preview
 
 echo "Updating lockfile..."