Documentation: Recommend using `pipx` for installation (PEP 668)

[bmunkholm]

Documentation feedback

• Page title: Getting started
• Page URL: https://cratedb.com/docs/crate/crash/en/latest/getting-started.html
• Source: https://github.com/crate/crash/blob/master/docs/getting-started.rst

---

When installing as a python package, should we not recommend using pipx instead of pip to avoid dependency conflicts?

[amotl]

Dear Brian,

apologies for the late reply, and thanks for your report. Indeed, I only recently became aware that newer distributions of Linux rightfully deny pip acting upon the system Python installation by default, effectively implementing PEP 668 – »Marking Python base environments as “externally managed”«, now the Externally Managed Environments guide.

This procedure succeeded until Debian Bullseye, but fails with Bookworm.

docker run --rm -it debian:bullseye bash
docker run --rm -it debian:bookworm bash

apt-get update
apt-get install --yes python3-pip
pip install crash

With kind regards,
Andreas.

/cc @surister, @simonprickett, @kneth

Error

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.

[amotl]

OT

If someone reading this, by chance, needs to override this on a system, CI or otherwise ephemeral configuration, or even persistently (don't!), those are two variants, applicable for both the pip and uv package managers.

Disable error: externally-managed-environment by environment variables.

# https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-break-system-packages
# https://docs.astral.sh/uv/reference/settings/#pip_break-system-packages
PIP_BREAK_SYSTEM_PACKAGES: true
UV_BREAK_SYSTEM_PACKAGES: true

Disable error: externally-managed-environment by configuration.

# https://docs.astral.sh/uv/reference/settings/#pip_break-system-packages
mkdir -p ~/.config/pip
mkdir -p ~/.config/uv
echo -e "[global]\nbreak-system-packages = true" > ~/.config/pip/pip.conf
echo -e "[tool.uv.pip]\nbreak-system-packages = true" > ~/.config/uv/uv.toml

[amotl]

Solution: Using pipx

@bmunkholm: Thanks for suggesting pipx. Which solution would you prefer to advertise? All of them?

apt-get update
apt-get install --yes pipx
pipx ensurepath
pipx install crash

This command variant would also work, but adds verbosity.

pipx run crash --version

This variant would be sensible for system-wide installation, also using pipx.

export PIPX_BIN_DIR=/usr/local/bin
pipx install crash
crash --version

[amotl]

Solution: Using uv

Another promising installation variant would be to use the uv package manager. That would roughly look like this:

docker run --rm -it debian:bookworm bash
apt-get update && apt-get install --yes curl
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env
uv venv
uv pip install crash
uv run crash --version

Note that uv can also be installed using pip or pipx: pipx install uv. ;]

Note that your system will not even need a Python installation. The first invocation of uv venv will transparently download a Python that will be hosted separately from your system. The roundtrip speed is insane.

Including Python installation

time (uv venv; uv pip install crash; uv run crash --version)

real	0m6.025s
user	0m1.930s
sys	0m1.726s

Excluding Python installation

time (uv venv; uv pip install crash; uv run crash --version)

real	0m1.651s
user	0m1.025s
sys	0m0.265s

NB: Python has been installed beforehand using uv python install 3.13.

[amotl]

Hi again. GH-451 implements a minimal update to relevant documentation sections, thanks. Feel free to submit any kinds of fixes yourself, we appreciate improvements of any size and matter. 🙏