PEP 668: Moving a VENV breaks it as its path variable is hard coded and absolute.

[RustoMCSpit]

Documentation

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.

This message is provided by my distro, Linux Mint. That's not your problem and that's reported here linuxmint/cinnamon#12765

When I went to your documentation, nothing included that this is usually caused by moving a venv file around.

Something like this could be added: "this error can be caused by moving the venv file around as the PATH is looking for it in its old location. Please run ''echo $PATHandwhich pip`` to confirm. Here is how to fix this!"

Nothing in /usr/share/doc/python3.12/README.venv includes anything on this

Additional Context

pypa/pip#13259 (comment)
pypa/virtualenv#2854

[pfmoore]

You reported this to the distro here: linuxmint/cinnamon#12765

That's where the message needs to be changed, so I'm not clear what you expect to happen here. As I said on the pip tracker, moving a virtual environment documented as something you shouldn't do, so ultimately your problem is user error. There's no documentation issue I can see, as "don't move virtual environments" is already documented.

[RustoMCSpit]

This is not about the error message, it's about python3.12/README.venv

Moving a venv as a common reason for an error occurring should be documented regardless.

[StanFromIreland]

It is?

[RustoMCSpit]

This is what I see at /usr/share/doc/python3.12

Installing Python Packages in Debian
====================================

It is recommended to let Debian's package managers manage Python packages in
/usr/lib/ and /usr/share/.

Python applications
-------------------

If you need to install a Python application (or version) that isn't packaged in
Debian, we recommend that you install it with pipx (in the "pipx" Debian
package). pipx will set up an environment isolated from other applications and
system Python modules, and install the application and its dependencies into
that.

Python library modules
----------------------

If you need to install a Python library module (or version) that isn't packaged
in Debian, we recommend installing it into a virtualenv, where possible. You
can create virtualenvs with the venv Python stdlib module (in the
"python3-venv" Debian package) or the virtualenv Python 3rd-party tool (in the
"virtualenv" Debian package).

Both of these will create an isolated environment, with a copy of pip in it.
After activating the environment, you can install python applications and
library modules into the virtual environment.

e.g. instead of running:
$ pip install --user foo
run:
$ mkdir -p ~/.venvs
$ python3 -m venv ~/.venvs/foo
$ ~/.venvs/foo/bin/python -m pip install foo

If needed, the isolated environment can also have access to system Python
modules, with the "--system-site-packages" flag.

Installing things system-wide
-----------------------------

Because Debian declares its Python install to be EXTERNALLY-MANAGED [0], pip
(and other installers) will refuse to install packages system-wide.
Installation is only possible in virtual environments or separate Python
installs.

[0]: https://peps.python.org/pep-0668/

This is because Python package installers (like pip) are unaware of the
constraints that APT-managed packages have on libraries and versions. See
PEP-668 for a full discussion of the problems that can occur when multiple
installers operate on the same Python install.

This can be overriden by passing the --break-system-packages option to pip. You
do this at your own risk: pip may break Python modules that part of your Debian
system depends on. This option can also be specified by exporting
PIP_BREAK_SYSTEM_PACKAGES=1 or configuring the following in
~/.config/pip/pip.conf or /etc/pip.conf:

[global]
break-system-packages = true

You can also override this system-wide by removing
/usr/lib/python3.*/EXTERNALLY-MANAGED. Again, you do this at your own risk,
with the understanding that Debian-provided Python modules may be broken by pip
/ other installers. The best way to do this is to move it with dpkg-divert,
which will survive security updates):

# dpkg-divert --rename --add /usr/lib/$(py3versions -d)/EXTERNALLY-MANAGED

A clean option is to install your own Python (from source) in /usr/local, that
isn't EXTERNALLY-MANAGED.

[StanFromIreland]

Installing Python Packages in Debian

This is part of Debian-packaged python, not maintained by CPython.