Bug#1049962: python3-pip: Misleading error message on "pip install --user"

[Ralf Jung]

Package: python3-pip
Version: 23.2+dfsg-1
Severity: normal

Dear Maintainer,

When I try to install something to my user directory, I get a confusing error message:

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.11/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 is confusing because the error, and the README.venv file, all talk about system-wide installation (in /usr). But I am not trying to do a system-wide installation!
I just want a user-wide installation. Somehow that leads to the same error message though.

Kind regards,
Ralf

-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 6.4.0-2-amd64 (SMP w/20 CPU threads; PREEMPT)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US:en
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages python3-pip depends on:
ii ca-certificates 20230311
ii python3 3.11.4-5
ii python3-distutils 3.11.4-1
ii python3-setuptools 68.0.0-1
ii python3-wheel 0.38.4-2

Versions of packages python3-pip recommends:
ii build-essential 12.10
ii python3-dev 3.11.4-5

python3-pip suggests no packages.

-- no debconf information

[Ralf Jung]

I still think the text and definitely the README.venv could be written in a less
confusing way. For instance, README.venv starts out saying

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

So for my case ("pip install --user"), obviously this document is not relevant,
since indeed I do want to let Debian manage the packages in /usr. Nothing in
that file even mentions ~/.local.

; Ralf

[Stefano Rivera]

Hi Ralf (2023.08.17_17:50:18_+0000)

> I still think the text and definitely the README.venv could be written in a
> less confusing way. For instance, README.venv starts out saying

Patches welcome :)

It's tricky to try to keep something short enough that people read it,
while still getting critical information across. I did my best, but...
:)

> > It is recommended to let Debian's package managers manage Python packages in
> > /usr/lib/ and /usr/share/.
>
> So for my case ("pip install --user"), obviously this document is not
> relevant, since indeed I do want to let Debian manage the packages in /usr.
> Nothing in that file even mentions ~/.local.

That's a fair point. How's this?

https://salsa.debian.org/cpython-team/python3/-/merge_requests/31

Stefano

--
Stefano Rivera
http://tumbleweed.org.za/
+1 415 683 3272