Implement --break-system-packages for EXTERNALLY-MANAGED installations (#11780)

The PEP 668 expects an override mechanism to ease the transition. This provides an override. --------- Co-authored-by: Pradyun Gedam <pradyunsg@gmail.com>

Author: stefanor

news/11780.feature.rst

@@ -0,0 +1,2 @@
+Implement ``--break-system-packages`` to permit installing packages into
+``EXTERNALLY-MANAGED`` Python installations.

src/pip/_internal/cli/cmdoptions.py

@@ -164,6 +164,14 @@ class PipOption(Option):
  ),
 )
 
+override_externally_managed: Callable[..., Option] = partial(
+ Option,
+ "--break-system-packages",
+ dest="override_externally_managed",
+ action="store_true",
+ help="Allow pip to modify an EXTERNALLY-MANAGED Python installation",
+)
+
 python: Callable[..., Option] = partial(
  Option,
  "--python",

src/pip/_internal/commands/install.py

@@ -215,6 +215,7 @@ def add_options(self) -> None:
  self.cmd_opts.add_option(cmdoptions.use_pep517())
  self.cmd_opts.add_option(cmdoptions.no_use_pep517())
  self.cmd_opts.add_option(cmdoptions.check_build_deps())
+ self.cmd_opts.add_option(cmdoptions.override_externally_managed())
 
  self.cmd_opts.add_option(cmdoptions.config_settings())
  self.cmd_opts.add_option(cmdoptions.install_options())
@@ -296,7 +297,10 @@ def run(self, options: Values, args: List[str]) -> int:
  and options.target_dir is None
  and options.prefix_path is None
  )
- if installing_into_current_environment:
+ if (
+ installing_into_current_environment
+ and not options.override_externally_managed
+ ):
  check_externally_managed()
 
  upgrade_strategy = "to-satisfy-only"

src/pip/_internal/commands/uninstall.py

@@ -58,6 +58,7 @@ def add_options(self) -> None:
  help="Don't ask for confirmation of uninstall deletions.",
  )
  self.cmd_opts.add_option(cmdoptions.root_user_action())
+ self.cmd_opts.add_option(cmdoptions.override_externally_managed())
  self.parser.insert_option_group(0, self.cmd_opts)
 
  def run(self, options: Values, args: List[str]) -> int:
@@ -93,7 +94,8 @@ def run(self, options: Values, args: List[str]) -> int:
  f'"pip help {self.name}")'
  )
 
- check_externally_managed()
+ if not options.override_externally_managed:
+ check_externally_managed()
 
  protect_pip_from_modification_on_windows(
  modifying_pip="pip" in reqs_to_uninstall

src/pip/_internal/exceptions.py

@@ -696,7 +696,9 @@ def __init__(self, error: Optional[str]) -> None:
  context=context,
  note_stmt=(
  "If you believe this is a mistake, please contact your "
- "Python installation or OS distribution provider."
+ "Python installation or OS distribution provider. "
+ "You can override this, at the risk of breaking your Python "
+ "installation or OS, by passing --break-system-packages."
  ),
  hint_stmt=Text("See PEP 668 for the detailed specification."),
  )

tests/functional/test_pep668.py

@@ -42,6 +42,22 @@ def test_fails(script: PipTestEnvironment, arguments: List[str]) -> None:
  assert "I am externally managed" in result.stderr
 
 
+@pytest.mark.parametrize(
+ "arguments",
+ [
+ pytest.param(["install"], id="install"),
+ pytest.param(["install", "--dry-run"], id="install-dry-run"),
+ pytest.param(["uninstall", "-y"], id="uninstall"),
+ ],
+)
+@pytest.mark.usefixtures("patch_check_externally_managed")
+def test_succeeds_when_overridden(
+ script: PipTestEnvironment, arguments: List[str]
+) -> None:
+ result = script.pip(*arguments, "pip", "--break-system-packages")
+ assert "I am externally managed" not in result.stderr
+
+
 @pytest.mark.parametrize(
  "arguments",
  [