Skip to content

Conversation

@SethFalco
Copy link
Member

Using pip3 install to install PyPI packages can cause headache, or worse, break system packages on Linux distributions.

Vladimyr did a good write-up about it on our Matrix chat:
https://matrix.to/#/!HiSKnvVsCpWxkTWWMC:gitter.im/$_8RsjYQBQIIcOGfhrJNm2fvex3O9tWnn0lhIb8riX5M?via=gitter.im&via=matrix.org&via=one.ems.host

Debian would also yell at me if I tried to follow those instructions:

pip3 install tldr
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.

Meanwhile, I'd recommend suggesting pipx instead of pip3.

https://github.com/pypa/pipx

This creates a venv behind the scenes, isolating the package and it's dependencies from other system-wide packages, so there's no risk of conflict. In Python-land, it's also a common way to install binaries anyway, for example Poetry (a very popular package/project manager for Python) also recommends installing it with pipx.

@SethFalco SethFalco merged commit 8836a08 into main Nov 7, 2025
@SethFalco SethFalco deleted the SethFalco-patch-1 branch November 7, 2025 00:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants