add notes on how to handle "error: externally-managed-environment" during install/upgrade (#2160)

Author: khorne3

docs/deployment/add-semgrep-other-ci.md

@@ -66,6 +66,7 @@ To create a `SEMGREP_APP_TOKEN`, follow these steps:
 1. Add Semgrep to your CI pipeline. Do either of the following:
     1. Reference or add the [Semgrep Docker image](https://hub.docker.com/r/semgrep/semgrep). This is the recommended method.
     2. Add `pip install semgrep` into your configuration file as a step or command, depending on your CI provider's syntax.
+         - If you see an error during the installation process due to your Python environment being externally managed by a package manager, see [Semgrep's article for instructions on how to proceed](/kb/semgrep-appsec-platform/error-externally-managed-environment).
 2. Add `semgrep ci` as a step or command.
 3. Set the `SEMGREP_APP_TOKEN` environment variable within your configuration file.
 

docs/getting-started/quickstart.md

@@ -77,6 +77,9 @@ You must have Python 3.9 or later installed on the machine where the Semgrep CLI
         # install through pip
         python3 -m pip install semgrep
 
+        # if you get the following error "error: externally-managed-environment",
+        # see semgrep.dev/docs/kb/semgrep-appsec-platform/error-externally-managed-environment 
+
         # confirm installation succeeded by printing the currently installed version
         semgrep --version
         ```

docs/kb/semgrep-appsec-platform/error-externally-managed-environment.md

@@ -0,0 +1,83 @@
+---
+description: Learn how to handle externally managed environment errors when installing Semgrep using pip.
+tags:
+ - Semgrep AppSec Platform
+ - Semgrep Code
+ - Semgrep Secrets
+ - Semgrep Supply Chain
+---
+
+# error: externally-managed-environment
+
+If your Python environment is [externally managed by a package manager](https://packaging.python.org/en/latest/specifications/externally-managed-environments/), you can't use `pip` for system-wide installations. This results in the `externally-managed-environment` when you try to use `pip` to install Semgrep.
+
+Error message on macOS:
+
+```console
+error: externally-managed-environment
+
+× This environment is externally managed
+╰─> To install Python packages system-wide, try brew install
+ xyz, where xyz is the package you are trying to
+ install.
+    
+ If you wish to install a Python library that isn't in Homebrew,
+ use a virtual environment:
+    
+ python3 -m venv path/to/venv
+ source path/to/venv/bin/activate
+ python3 -m pip install xyz
+    
+ If you wish to install a Python application that isn't in Homebrew,
+ it may be easiest to use 'pipx install xyz', which will manage a
+ virtual environment for you. You can install pipx with
+    
+ brew install pipx
+    
+ You may restore the old behavior of pip by passing
+ the '--break-system-packages' flag to pip, or by adding
+ 'break-system-packages = true' to your pip.conf file. The latter
+ will permanently disable this error.
+    
+ If you disable this error, we STRONGLY recommend that you additionally
+ pass the '--user' flag to pip, or set 'user = true' in your pip.conf
+ file. Failure to do this can result in a broken Homebrew installation.
+    
+ Read more about this behavior here: <https://peps.python.org/pep-0668/>
+
+note: If you believe this is a mistake, please contact your 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: See PEP 668 for the detailed specification.
+```
+
+Error message on Ubuntu:
+
+```console
+error: externally-managed-environment
+
+× This environment is externally managed
+╰─> To install Python packages system-wide, try apt install
+ python3-xyz, where xyz is the package you are trying to
+ install.
+    
+ If you wish to install a non-Debian-packaged Python package,
+ create a virtual environment using python3 -m venv path/to/venv.
+ Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
+ sure you have python3-full installed.
+    
+ If you wish to install a non-Debian packaged Python application,
+ it may be easiest to use pipx install xyz, which will manage a
+ virtual environment for you. Make sure you have pipx installed.
+    
+ See /usr/share/doc/python3.12/README.venv for more information.
+
+note: If you believe this is a mistake, please contact your 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: See PEP 668 for the detailed specification.
+```
+
+## How to fix this error
+
+For most users, the simplest solution is to install [`pipx`](https://github.com/pypa/pipx), then run `pipx install semgrep` to install Semgrep. `pipx` automatically creates and manages virtual environments for standalone Python applications.
+
+You can also install Semgrep using [`homebrew`](https://brew.sh/).
+
+If you're already using a custom Python virtual environment, you can install Semgrep in this existing environment instead.

docs/kb/semgrep-code/run-specific-version.md

@@ -23,6 +23,8 @@ Install a specific Semgrep version using pip's version syntax:
 
 <pre class="language-bash"><code>python3 -m pip install semgrep==<span className="placeholder">x.y.z</span></code></pre>
 
+If you see an error during the installation process due to your Python environment being externally managed by a package manager, see [Semgrep's article for instructions on how to proceed](/kb/semgrep-appsec-platform/error-externally-managed-environment).
+
 Confirm installation:
 
 ```

docs/semgrep-ci/sample-ci-configs.md

@@ -477,7 +477,7 @@ You can customize the scan by entering custom rules or other rulesets to scan wi
 
 To run Semgrep CI on any other provider, use the `semgrep/semgrep` image, and run the `semgrep ci` command with `SEMGREP_BASELINE_REF` set for diff-aware scanning.
 
-**Note**: If you need to use a different Docker image or are not running in Docker, install Semgrep CI by `pip install semgrep`.
+**Note**: If you need to use a different Docker image or are not running in Docker, install Semgrep CI by `pip install semgrep`. If you see an error during the installation process due to your Python environment being externally managed by a package manager, see [Semgrep's article for instructions on how to proceed](/kb/semgrep-appsec-platform/error-externally-managed-environment).
 
 By setting various [CI environment variables](/semgrep-ci/ci-environment-variables), you can run Semgrep in the following CI providers:
 

docs/semgrep-code/semgrep-pro-engine-intro.md

@@ -93,6 +93,9 @@ Cross-file analysis uses a separate `semgrep` binary. To update to the latest ve
 
     ```bash
     python3 -m pip install --upgrade semgrep
+
+    # if you get the following error "error: externally-managed-environment",
+    # see semgrep.dev/docs/kb/semgrep-appsec-platform/error-externally-managed-environment 
     ```
 
     </TabItem>

docs/update.md

@@ -32,6 +32,10 @@ brew upgrade semgrep
 # macOS, Linux, or Windows Subsystem for Linux (WSL) users, using pip
 python3 -m pip install --upgrade semgrep
 
+# If you get the following error "error: externally-managed-environment", see
+# semgrep.dev/docs/kb/semgrep-appsec-platform/error-externally-managed-environment
+python3 -m pipx install --upgrade semgrep
+
 # confirm your Semgrep installation
 semgrep --version
 ```

src/components/procedure/_install-cli.mdx

@@ -11,6 +11,9 @@ brew install semgrep
 # macOS, Linux, or Windows Subsystem for Linux (WSL) users
 python3 -m pip install semgrep
 
+# if you get the following error "error: externally-managed-environment",
+# see semgrep.dev/docs/kb/semgrep-appsec-platform/error-externally-managed-environment 
+
 # confirm
 semgrep --version
 ```