From f4daeafca1814e83d7013770bfba4ae921c5f36c Mon Sep 17 00:00:00 2001
From: Jack O'Connor <jack@astral.sh>
Date: Thu, 29 May 2025 13:51:20 -0700
Subject: [PATCH] improve the explanation of the env var

---
 crates/uv-static/src/env_vars.rs  | 10 +++++++---
 docs/configuration/environment.md | 10 +++++++---
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/crates/uv-static/src/env_vars.rs b/crates/uv-static/src/env_vars.rs
index 9a211b956..5b10fa4e0 100644
--- a/crates/uv-static/src/env_vars.rs
+++ b/crates/uv-static/src/env_vars.rs
@@ -256,9 +256,13 @@ impl EnvVars {
     /// for more details.
     pub const UV_PROJECT_ENVIRONMENT: &'static str = "UV_PROJECT_ENVIRONMENT";
 
-    /// Equivalent to the `--active` command line argument. If set, uv will look at `VIRTUAL_ENV`
-    /// and use the active virtual environment, if any. If `VIRTUAL_ENV` is not defined, this has
-    /// no effect.
+    /// Equivalent to the `--active` command line argument for commands that support it. For
+    /// example, when running inside a project or when running a script with inline metadata,
+    /// `uv run` manages its own virtual environment and ignores the caller's active environment
+    /// (i.e. the `VIRTUAL_ENV` environment variable). Similarly, `uv sync` and `uv add` expect to
+    /// run in a project, and they use the managed virtual environment by default. The active
+    /// option causes these commands to use the caller's active virtual environment instead, if
+    /// there is one.
     pub const UV_USE_ACTIVE_ENVIRONMENT: &'static str = "UV_USE_ACTIVE_ENVIRONMENT";
 
     /// Specifies the directory to place links to installed, managed Python executables.
diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md
index 2e5f67735..ae1d9d4a1 100644
--- a/docs/configuration/environment.md
+++ b/docs/configuration/environment.md
@@ -431,9 +431,13 @@ the installer from modifying shell profiles or environment variables.
 
 ### `UV_USE_ACTIVE_ENVIRONMENT`
 
-Equivalent to the `--active` command line argument. If set, uv will look at `VIRTUAL_ENV`
-and use the active virtual environment, if any. If `VIRTUAL_ENV` is not defined, this has
-no effect.
+Equivalent to the `--active` command line argument for commands that support it. For
+example, when running inside a project or when running a script with inline metadata,
+`uv run` manages its own virtual environment and ignores the caller's active environment
+(i.e. the `VIRTUAL_ENV` environment variable). Similarly, `uv sync` and `uv add` expect to
+run in a project, and they use the managed virtual environment by default. The active
+option causes these commands to use the caller's active virtual environment instead, if
+there is one.
 
 ### `UV_VENV_SEED`