pip Wisdom

pip is the most-used and most-misused tool in this quest. These rules separate Python developers whose environments work from those who fight their environments daily.

Always use virtual environments. Never sudo pip. Globally installing packages mixes them with system Python's libs and breaks both. Every Python project deserves its own venv.

Use python3 -m venv, not virtualenv. The stdlib venv module is built in and good enough. The third-party virtualenv package adds features most users don't need and is a relic of the Python 2 era.

Use pip-tools if you need real reproducibility on pip. pip-compile turns a small requirements.in into a fully-pinned requirements.txt. It's the right answer for projects that want strict reproducibility but can't switch to uv yet.

Consider uv for new Python projects. uv is 10-100x faster, has a real lockfile, manages Python versions, and replaces pip + venv + pip-tools + pyenv + pipx in one binary. The next track is dedicated to it.

Mind macOS PEP 668. Newer macOS Pythons restrict global pip installs to prevent breaking system tools. The error is 'externally-managed-environment'. The right fix is to use a venv. The wrong fix is --break-system-packages.

Code

PEP 668 — the externally-managed error·bash

# Symptom
pip install requests
# error: externally-managed-environment
#
# This environment is externally managed
# To install Python packages system-wide, try ...

# Right fix: use a venv
python3 -m venv .venv
source .venv/bin/activate
pip install requests

# Wrong fix: bypass with --break-system-packages
# Don't do this. It's literally what the flag is named.

Auto-activate venv with direnv·bash

# Install direnv
brew install direnv

# Add hook to ~/.zprofile
echo 'eval "$(direnv hook zsh)"' >> ~/.zprofile

# In your project root, create .envrc
echo 'source .venv/bin/activate' > .envrc
direnv allow

# Now: cd into the project, venv auto-activates.
# cd out, venv auto-deactivates.

Code

External links

Exercise

Progress

Comments 0