Re: commands to do "pip install" in docs README file need enhancing

[<tgamblin@baylibre.com>]

On Thu Aug 20, 2026 at 7:20 AM EDT, Robert P. J. Day wrote:
>
>   I just went through this with another Sphinx-based documentation
> repo -- installation instructions that advise the reader to install
> Python modules with "pip install" fail on my Debian 13 system with:
>
>
> $ pip install sphinx-lint
> 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.13/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.
>
>
>   Yes, there are solutions, such as using "pipx" instead of "pip", and
> what have you, but it seems that the README file should be augmented
> with an explanation as to how to deal with the above given that the
> "pip install" commands are, in some cases, guaranteed to fail.

Creating a venv like the error suggests (or via uv) is simple enough and IMO
best practice for anything like this. You could submit a change to provide short
examples, even replacing the references to pipenv earlier in the file.
>
> rday