search

crate / crash

Crash is an interactive CrateDB command line interface (CLI) SQL shell with autocompletion.
Apache License 2.0
48 stars 13 forks source link

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

Closed bmunkholm closed 1 week ago

bmunkholm commented 1 month ago

Documentation feedback

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

amotl commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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. 🙏