Python CLI-tools op macOS via pipx
Definitie
Op macOS met Homebrew Python is pip install op systeemniveau geblokkeerd door PEP 668. Voor Python CLI-tools die globaal bereikbaar moeten zijn is pipx de standaardaanpak. Pipx installeert elke tool in een eigen virtual environment en plaatst de CLI-entrypoints in ~/.local/bin/.
Context
Homebrew-geleverde Python volgt PEP 668 en markeert zich als een externally managed environment. Een globale pip install <pakket> geeft dan:
error: externally-managed-environment
× This environment is externally managed
Dit voorkomt dat gebruikers per ongeluk Homebrew’s Python-installatie vervuilen met packages die conflicten opleveren bij een brew upgrade. De aanbevolen uitweg is pipx voor globale CLI-tools of een dedicated venv voor project-afhankelijkheden.
Kernpunten
Wanneer pipx gebruiken
Pipx is voor Python-packages die je op de command line als globale tool wilt aanroepen, zoals cozempic, black, poetry, ruff, httpie. Niet voor library-afhankelijkheden van een project, daar gebruik je een venv of poetry/uv.
Installatie
brew install pipx
pipx ensurepath
ensurepath zorgt dat ~/.local/bin in je PATH staat. Shell herstarten of het profiel herladen.
Een CLI-tool installeren
pipx install cozempic
Pipx maakt een venv onder ~/.local/pipx/venvs/<pakket>/, installeert het pakket plus dependencies geisoleerd, en linkt de entrypoint naar ~/.local/bin/<tool>. Geen conflicten met Homebrew Python, geen vervuiling van andere tools.
Upgraden en verwijderen
pipx upgrade cozempic
pipx upgrade-all
pipx uninstall cozempic
pipx list
Alternatieven en hun afwegingen
| Methode | Wanneer | Nadeel |
|---|---|---|
| pipx | Globale CLI-tools | Extra laag, venv per tool |
| venv per project | Project dependencies | Niet globaal bereikbaar |
pip install --break-system-packages | Noodgreep | Riskeert Homebrew Python kapot |
pip install --user | Per-user install | Werkt niet altijd op Homebrew Python |
uv tool install | Moderne vervanger | Vereist uv apart installeren |
--break-system-packages werkt wel maar kan bij Homebrew-upgrades tot verrassingen leiden. Alleen gebruiken als je weet wat je doet en je de gevolgen kunt herstellen.
Typische foutmelding als signaal
Een externally-managed-environment fout is het signaal om naar pipx te switchen. De fout komt altijd van Homebrew Python of distro-geleverde Python op Debian-achtige systemen. Pyenv- of uv-geinstalleerde Python heeft deze restrictie niet.
Pipx-venv locatie
Elk pakket krijgt een eigen map onder ~/.local/pipx/venvs/<pakket>/. Handig voor debugging of voor het handmatig aanroepen van de Python binnen die venv (bijvoorbeeld om te kijken welke afhankelijkheden er staan).
Verbanden
- Zie ook: wiki-cozempic-context-cleaning
- Zie ook: wiki-claude-workspace-setup
Bronnen
- PEP 668, Marking Python base environments as “externally managed”, Python Enhancement Proposals.