Allow the project `VIRTUAL_ENV` warning to be silenced with `--no-active` (#11251)

Follow-up to https://github.com/astral-sh/uv/pull/11189

Closes https://github.com/astral-sh/uv-pre-commit/issues/36

crates/uv-workspace/src/workspace.rs

@@ -538,7 +538,11 @@ impl Workspace {
     ///
     /// If `UV_PROJECT_ENVIRONMENT` is set, it will take precedence. If a relative path is provided,
     /// it is resolved relative to the install path.
-    pub fn venv(&self, active: bool) -> PathBuf {
+    ///
+    /// If `active` is `true`, the `VIRTUAL_ENV` variable will be preferred. If it is `false`, any
+    /// warnings about mismatch between the active environment and the project environment will be
+    /// silenced.
+    pub fn venv(&self, active: Option<bool>) -> PathBuf {
         /// Resolve the `UV_PROJECT_ENVIRONMENT` value, if any.
         fn from_project_environment_variable(workspace: &Workspace) -> Option<PathBuf> {
             let value = std::env::var_os(EnvVars::UV_PROJECT_ENVIRONMENT)?;
@@ -606,24 +610,31 @@ impl Workspace {
         // Warn if it conflicts with `VIRTUAL_ENV`
         if let Some(from_virtual_env) = from_virtual_env_variable() {
             if !is_same_dir(&from_virtual_env, &project_env).unwrap_or(false) {
-                if active {
-                    debug!(
-                        "Using active virtual environment `{}` instead of project environment `{}`",
-                        from_virtual_env.user_display(),
-                        project_env.user_display()
-                    );
-                    return from_virtual_env;
+                match active {
+                    Some(true) => {
+                        debug!(
+                            "Using active virtual environment `{}` instead of project environment `{}`",
+                            from_virtual_env.user_display(),
+                            project_env.user_display()
+                        );
+                        return from_virtual_env;
+                    }
+                    Some(false) => {}
+                    None => {
+                        warn_user_once!(
+                            "`VIRTUAL_ENV={}` does not match the project environment path `{}` and will be ignored; use `--active` to target the active environment instead",
+                            from_virtual_env.user_display(),
+                            project_env.user_display()
+                        );
+                    }
                 }
-                warn_user_once!(
-                    "`VIRTUAL_ENV={}` does not match the project environment path `{}` and will be ignored; use `--active` to target the active environment instead",
-                    from_virtual_env.user_display(),
-                    project_env.user_display()
-                );
             }
         } else {
-            debug!(
-                "Use of the active virtual environment was requested, but `VIRTUAL_ENV` is not set"
-            );
+            if active.unwrap_or_default() {
+                debug!(
+                    "Use of the active virtual environment was requested, but `VIRTUAL_ENV` is not set"
+                );
+            }
         }
 
         project_env

crates/uv/src/commands/project/add.rs

@@ -61,7 +61,7 @@ pub(crate) async fn add(
     project_dir: &Path,
     locked: bool,
     frozen: bool,
-    active: bool,
+    active: Option<bool>,
     no_sync: bool,
     requirements: Vec<RequirementsSource>,
     editable: Option<bool>,
@@ -233,8 +233,8 @@ pub(crate) async fn add(
                 connectivity,
                 native_tls,
                 allow_insecure_host,
-                active,
                 no_config,
+                active,
                 cache,
                 printer,
             )

crates/uv/src/commands/project/export.rs

@@ -163,7 +163,7 @@ pub(crate) async fn export(
                 allow_insecure_host,
                 &install_mirrors,
                 no_config,
-                false,
+                Some(false),
                 cache,
                 printer,
             )

crates/uv/src/commands/project/lock.rs

@@ -121,7 +121,7 @@ pub(crate) async fn lock(
                 allow_insecure_host,
                 &install_mirrors,
                 no_config,
-                false,
+                Some(false),
                 cache,
                 printer,
             )

crates/uv/src/commands/project/mod.rs

@@ -602,7 +602,7 @@ impl ProjectInterpreter {
         allow_insecure_host: &[TrustedHost],
         install_mirrors: &PythonInstallMirrors,
         no_config: bool,
-        active: bool,
+        active: Option<bool>,
         cache: &Cache,
         printer: Printer,
     ) -> Result<Self, ProjectError> {
@@ -925,7 +925,7 @@ pub(crate) async fn get_or_init_environment(
     native_tls: bool,
     allow_insecure_host: &[TrustedHost],
     no_config: bool,
-    active: bool,
+    active: Option<bool>,
     cache: &Cache,
     printer: Printer,
 ) -> Result<PythonEnvironment, ProjectError> {

crates/uv/src/commands/project/remove.rs

@@ -43,7 +43,7 @@ pub(crate) async fn remove(
     project_dir: &Path,
     locked: bool,
     frozen: bool,
-    active: bool,
+    active: Option<bool>,
     no_sync: bool,
     packages: Vec<PackageName>,
     dependency_type: DependencyType,

crates/uv/src/commands/project/run.rs

@@ -65,7 +65,7 @@ pub(crate) async fn run(
     show_resolution: bool,
     locked: bool,
     frozen: bool,
-    active: bool,
+    active: Option<bool>,
     no_sync: bool,
     isolated: bool,
     all_packages: bool,

crates/uv/src/commands/project/sync.rs

@@ -45,7 +45,7 @@ pub(crate) async fn sync(
     project_dir: &Path,
     locked: bool,
     frozen: bool,
-    active: bool,
+    active: Option<bool>,
     all_packages: bool,
     package: Option<PackageName>,
     extras: ExtrasSpecification,

crates/uv/src/commands/project/tree.rs

@@ -118,7 +118,7 @@ pub(crate) async fn tree(
                 allow_insecure_host,
                 &install_mirrors,
                 no_config,
-                false,
+                Some(false),
                 cache,
                 printer,
             )

crates/uv/src/commands/venv.rs

@@ -187,7 +187,7 @@ async fn venv_impl(
                 // This isn't strictly necessary and we may want to change it later, but this
                 // avoids a breaking change when adding project environment support to `uv venv`.
                 (project.workspace().install_path() == project_dir)
-                    .then(|| project.workspace().venv(false))
+                    .then(|| project.workspace().venv(Some(false)))
             })
             .unwrap_or(PathBuf::from(".venv")),
     );

crates/uv/src/settings.rs

@@ -289,7 +289,7 @@ pub(crate) struct RunSettings {
     pub(crate) all_packages: bool,
     pub(crate) package: Option<PackageName>,
     pub(crate) no_project: bool,
-    pub(crate) active: bool,
+    pub(crate) active: Option<bool>,
     pub(crate) no_sync: bool,
     pub(crate) python: Option<String>,
     pub(crate) install_mirrors: PythonInstallMirrors,
@@ -391,7 +391,7 @@ impl RunSettings {
             package,
             no_project,
             no_sync,
-            active: flag(active, no_active).unwrap_or_default(),
+            active: flag(active, no_active),
             python: python.and_then(Maybe::into_option),
             refresh: Refresh::from(refresh),
             settings: ResolverInstallerSettings::combine(
@@ -956,7 +956,7 @@ impl PythonPinSettings {
 pub(crate) struct SyncSettings {
     pub(crate) locked: bool,
     pub(crate) frozen: bool,
-    pub(crate) active: bool,
+    pub(crate) active: Option<bool>,
     pub(crate) extras: ExtrasSpecification,
     pub(crate) dev: DevGroupsSpecification,
     pub(crate) editable: EditableMode,
@@ -1017,7 +1017,7 @@ impl SyncSettings {
         Self {
             locked,
             frozen,
-            active: flag(active, no_active).unwrap_or_default(),
+            active: flag(active, no_active),
             extras: ExtrasSpecification::from_args(
                 flag(all_extras, no_all_extras).unwrap_or_default(),
                 no_extra,
@@ -1107,7 +1107,7 @@ impl LockSettings {
 pub(crate) struct AddSettings {
     pub(crate) locked: bool,
     pub(crate) frozen: bool,
-    pub(crate) active: bool,
+    pub(crate) active: Option<bool>,
     pub(crate) no_sync: bool,
     pub(crate) packages: Vec<String>,
     pub(crate) requirements: Vec<PathBuf>,
@@ -1220,7 +1220,7 @@ impl AddSettings {
         Self {
             locked,
             frozen,
-            active: flag(active, no_active).unwrap_or_default(),
+            active: flag(active, no_active),
             no_sync,
             packages,
             requirements,
@@ -1251,7 +1251,7 @@ impl AddSettings {
 pub(crate) struct RemoveSettings {
     pub(crate) locked: bool,
     pub(crate) frozen: bool,
-    pub(crate) active: bool,
+    pub(crate) active: Option<bool>,
     pub(crate) no_sync: bool,
     pub(crate) packages: Vec<PackageName>,
     pub(crate) dependency_type: DependencyType,
@@ -1308,7 +1308,7 @@ impl RemoveSettings {
         Self {
             locked,
             frozen,
-            active: flag(active, no_active).unwrap_or_default(),
+            active: flag(active, no_active),
             no_sync,
             packages,
             dependency_type,

crates/uv/tests/it/lock.rs

@@ -14643,7 +14643,6 @@ fn lock_explicit_default_index() -> Result<()> {
     DEBUG Found workspace root: `[TEMP_DIR]/`
     DEBUG Adding current workspace member: `[TEMP_DIR]/`
     DEBUG Using Python request `>=3.12` from `requires-python` metadata
-    DEBUG Use of the active virtual environment was requested, but `VIRTUAL_ENV` is not set
     DEBUG Checking for Python environment at `.venv`
     DEBUG The virtual environment's Python version satisfies `>=3.12`
     DEBUG Using request timeout of [TIME]

crates/uv/tests/it/run.rs

@@ -3467,6 +3467,21 @@ fn run_active_environment() -> Result<()> {
      + iniconfig==2.0.0
     "###);
 
+    // Using `--no-active` should silence the warning
+    uv_snapshot!(context.filters(), context.run()
+        .arg("--no-active")
+        .arg("python").arg("--version")
+        .env(EnvVars::VIRTUAL_ENV, "foo"), @r###"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    Python 3.11.[X]
+
+    ----- stderr -----
+    Resolved 2 packages in [TIME]
+    Audited 1 package in [TIME]
+    "###);
+
     context
         .temp_dir
         .child(".venv")

docs/concepts/projects/config.md

@@ -192,7 +192,8 @@ To target this environment, you'd export `UV_PROJECT_ENVIRONMENT=/usr/local`.
 
     By default, uv does not read the `VIRTUAL_ENV` environment variable during project operations.
     A warning will be displayed if `VIRTUAL_ENV` is set to a different path than the project's
-    environment. The `--active` flag can be used to opt-in to respecting `VIRTUAL_ENV`.
+    environment. The `--active` flag can be used to opt-in to respecting `VIRTUAL_ENV`. The
+    `--no-active` flag can be used to silence the warning.
 
 ## Limited resolution environments