From d03e9f2b8c52e0eb70ceaec6b0df451abbbad948 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Thu, 11 Apr 2024 11:58:00 -0400
Subject: [PATCH] Add `UV_BREAK_SYSTEM_PACKAGES` environment variable (#2995)

## Summary

Requested here: https://github.com/astral-sh/uv/issues/2988. Seems
reasonable to me given that pip supports it and we already have
`UV_SYSTEM_PYTHON`.

Closes https://github.com/astral-sh/uv/issues/2988
---
 README.md             | 13 ++++++++++---
 crates/uv/src/main.rs |  6 +++---
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 74ba5ef93..a41081cc4 100644
--- a/README.md
+++ b/README.md
@@ -453,10 +453,17 @@ uv accepts the following command-line arguments as environment variables:
   `lowest-direct`, uv will install the lowest compatible versions of all direct dependencies.
 - `UV_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to
   `allow`, uv will allow pre-release versions for all dependencies.
-- `UV_SYSTEM_PYTHON`:  Equivalent to the `--system` command-line argument. If set to `true`, uv
+- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv
   will use the first Python interpreter found in the system `PATH`.
-  WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) environments and
-  should be used with caution, as it can modify the system Python installation.
+  WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) or
+  containerized environments and should be used with caution, as modifying the system Python
+  can lead to unexpected behavior.
+- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If
+  set to `true`, uv will allow the installation of packages that conflict with system-installed
+  packages.
+  WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration (CI) or
+  containerized environments and should be used with caution, as modifying the system Python
+  can lead to unexpected behavior.
 - `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv
   will use the system's trust store instead of the bundled `webpki-roots` crate.
 - `UV_INDEX_STRATEGY`: Equivalent to the `--index-strategy` command-line argument. For example, if
diff --git a/crates/uv/src/main.rs b/crates/uv/src/main.rs
index f20674194..d39b7198c 100644
--- a/crates/uv/src/main.rs
+++ b/crates/uv/src/main.rs
@@ -657,7 +657,7 @@ struct PipSyncArgs {
     /// environments, when installing into Python installations that are managed by an external
     /// package manager, like `apt`. It should be used with caution, as such Python installations
     /// explicitly recommend against modifications by other package managers (like `uv` or `pip`).
-    #[clap(long, requires = "discovery")]
+    #[clap(long, env = "UV_BREAK_SYSTEM_PACKAGES", requires = "discovery")]
     break_system_packages: bool,
 
     /// Use legacy `setuptools` behavior when building source distributions without a
@@ -941,7 +941,7 @@ struct PipInstallArgs {
     /// environments, when installing into Python installations that are managed by an external
     /// package manager, like `apt`. It should be used with caution, as such Python installations
     /// explicitly recommend against modifications by other package managers (like `uv` or `pip`).
-    #[clap(long, requires = "discovery")]
+    #[clap(long, env = "UV_BREAK_SYSTEM_PACKAGES", requires = "discovery")]
     break_system_packages: bool,
 
     /// Use legacy `setuptools` behavior when building source distributions without a
@@ -1086,7 +1086,7 @@ struct PipUninstallArgs {
     /// environments, when installing into Python installations that are managed by an external
     /// package manager, like `apt`. It should be used with caution, as such Python installations
     /// explicitly recommend against modifications by other package managers (like `uv` or `pip`).
-    #[clap(long, requires = "discovery")]
+    #[clap(long, env = "UV_BREAK_SYSTEM_PACKAGES", requires = "discovery")]
     break_system_packages: bool,
 
     /// Run offline, i.e., without accessing the network.