Post History

<section class="notice is-danger">

**Reminder: never use `sudo` to run Pip.** This can never properly fix a problem and only introduces serious security risks. Installing third-party packages from PyPI **can run arbitrary code at install time, by design**, so it should *never* be given root privileges.

Anyone who has observed using `sudo` for Pip to solve a problem, was misled. The *only* reason it might have helped is because the root user has a different `PATH`, resulting in<br>[a different Pip being used, corresponding to a different Python installation](https://software.codidact.com/posts/291675).

(Example commands involving `sudo` are deliberately not shown here, to avoid mindless copy-pasting.) 
</section>

## Overview

The situation is exactly as the error message describes, and the advice given is useful and will solve the problem:

* Your Python environment (i.e., the Python that was installed with your system, plus the libraries etc. that come with it) is "externally managed".

* Because of this, you are expected not to use Pip to install packages in that environment, but instead use the system package manager.

<section class="notice is-success">

If the system package manager doesn't provide the third-party library that you want, or if you don't want to use it, the most logical alternative is to set up a separate Python environment, by [using a virtual environment](https://software.codidact.com/posts/291740). This is the overall simplest and safest approach - leave the Python that came with the system alone, as much as possible, and use a separate Python for development.
</section>

## "External management" and [PEP 668](https://peps.python.org/pep-0668/)

When Pip calls the environment "externally managed", it means that some other program or tool is supposed to be responsible for installing packages, instead of Pip. Since [Python 3.11 and Pip 23.0](https://discuss.python.org/t/pep-668-marking-python-base-environments-as-externally-managed/10302/69), Pip has implemented the "marker" standard described in PEP 668 (the [documentation for this feature is now maintained separately](https://packaging.python.org/en/latest/specifications/externally-managed-environments/#externally-managed-environments)).

This allows Linux distro maintainers (and others) to add a specially named "marker" file to the folder that contains Python's standard library. When Pip sees that there is such a file *and* sees that it is *not* using a virtual environment, the error occurs. (Pip needs to disable the check for virtual environments because they use the base Python's standard library.)

The marker file can optionally include specific advice from the maintainer, which Pip will include in the error. The indented part after the arrow comes from the file; the error itself, as well as the "note" and "hint" at the bottom, are hard-coded by Pip.

Regarding the Debian-specific advice shown here: `python3-full` is a dependency package which will add multiple pieces to the system Python which are disabled by default - including `venv` (which you'll need in order to make virtual environments), [Tkinter](https://software.codidact.com/posts/291791) (and IDLE), `distutils` ([but not](https://software.codidact.com/posts/291340/) if your system Python is 3.12), and the "2to3" tool. It also adds a support library for GNU `dbm` database files. (However, it does *not* appear to include Pip.)

<section class="notice is-success">

**`apt install python3-venv` is enough if you just want to set up virtual environments.** The base Python might have `distutils` anyway; the 2to3 tool is irrelevant for almost everyone now; `dbm` files are a niche interest; and new virtual environments will bootstrap Pip. However, [your virtual environments won't include Tkinter unless they're created from a base that does](https://software.codidact.com/posts/291791). **Installing `python3-full` may be worthwhile if you need both venv support and Tkinter support.**

Of course, it's also possible to just do a completely separate Python installation. This would also allow you to choose a different version of Python.
</section>

Note that the advice about `pipx` is about installing Python *applications*, not libraries. As such, it's not really relevant for developers, usually.

## Other workarounds

<section class="notice is-warning">

**It's possible to circumvent the marker in a variety of ways, but please keep in mind that it exists for your protection.** Note that *even when circumvented*, Pip will default to a user-level installation (as if you used the `-U`/`--user` option) if it doesn't have root privileges. Again, **never use `sudo` to run Pip.**

Keep in mind that **even user-level installs can still "break" system packages** by, for example, shadowing the names of standard library or other modules that the system-included scripts would otherwise `import`.
</section>

Options here include:

* Pass the `--break-system-packages` option to Pip, as described. This is a simple confirmation that you accept the risk.

* [Set the `PIP_BREAK_SYSTEM_PACKAGES` environment variable](https://stackoverflow.com/a/76469774/523612) (also see [official documentation](https://pip.pypa.io/en/stable/topics/configuration/#environment-variables)), or [specify the `break-system-packages` option in your Pip configuration](https://stackoverflow.com/a/75722775/523612).

    To change the Pip configuration, edit your `~/.config/pip/pip.conf` file to include:

    ```ini
    [global]
    break-system-packages = true
    ```

    or [use the `pip config` command](https://pip.pypa.io/en/stable/cli/pip_config/):

    ```bash
    python -m pip config --global set global.break-system-packages true
    ```

    These approaches tell Pip to act as if the `--break-system-packages` flag were present for every command used.

* [Rename or remove](https://stackoverflow.com/a/76641565/523612) the marker file, which is named `EXTERNALLY-MANAGED` and will generally be in a location like `/usr/lib/python3.x` (according to the Python version). This will generally require root privileges.