macOS viene con Python instalado. Eso no es un regalo — es una trampa si no entiendes para qué está ahí.
El Python del sistema (en /usr/bin/python3 desde macOS 12.3 en adelante, o el antiguo /usr/bin/python en versiones anteriores) existe porque macOS lo necesita para sus propias herramientas internas: scripts de administración, Xcode, utilidades del sistema operativo. Apple lo mantiene, Apple lo versiona, y Apple no te está preguntando qué necesitas tú para tu proyecto. Si lo modificas — instalando paquetes con sudo pip, cambiando su versión, sobreescribiendo binarios — puedes dejar componentes del sistema en un estado inconsistente que es frustrante de depurar.
La regla es simple: el Python del sistema es de macOS, no tuyo. Necesitas tu propio Python, completamente separado.
Dos caminos: Homebrew o pyenv
Homebrew es el gestor de paquetes no oficial de macOS y la forma más rápida de tener un Python moderno funcionando. Con él instalado, un brew install python te da un Python en /opt/homebrew/bin/python3 (en Apple Silicon) o /usr/local/bin/python3 (en Intel), completamente aislado del sistema.
# Instalar Homebrew si aún no lo tienes /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Instalar Python brew install python
Esto funciona bien si solo necesitas una versión. El problema aparece cuando un proyecto requiere Python 3.9 y otro requiere 3.11 — Homebrew no gestiona eso elegantemente.
Ahí entra pyenv, una herramienta que te permite instalar y cambiar entre múltiples versiones de Python en el mismo equipo. No reemplaza a Homebrew; de hecho, pyenv se instala con Homebrew:
brew install pyenv
Luego añades estas líneas a tu archivo de configuración de shell (~/.zshrc en macOS moderno):
export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)"
Recarga el shell (source ~/.zshrc) y ya puedes instalar cualquier versión:
pyenv install 3.12.3 pyenv global 3.12.3 # versión por defecto en todo el sistema pyenv local 3.11.9 # versión específica para un directorio/proyecto
pyenv local crea un archivo .python-version en el directorio actual. Cada vez que entras a ese directorio, pyenv activa esa versión automáticamente. Es transparente y reversible.
El misterio de python vs python3
En macOS verás que python (sin el 3) a veces no existe o apunta a cosas distintas según la instalación. Esto viene de la transición de Python 2 a Python 3: durante años macOS mantuvo python para referirse a Python 2.7 y python3 para Python 3.x.
Con pyenv configurado correctamente, este problema desaparece: pyenv expone ambos comandos (python y python3) apuntando a la versión que hayas seleccionado. Puedes verificarlo:
which python # debería mostrar algo bajo ~/.pyenv/shims/ python --version python3 --version # ambos muestran la misma versión
Si aún estás viendo el Python del sistema o comportamientos inconsistentes, lo más probable es que las líneas de pyenv init no estén bien cargadas en tu shell.
El ejemplo completo: verificar que todo está en orden
# verify_env.py
# Run this after setting up your Python to confirm you're using the right one.
import sys
import sysconfig
def main():
version = sys.version_info
executable = sys.executable
stdlib_path = sysconfig.get_path("stdlib")
print(f"Python {version.major}.{version.minor}.{version.micro}")
print(f"Executable : {executable}")
print(f"Stdlib path: {stdlib_path}")
# Warn loudly if somehow using system Python
suspicious_paths = ["/usr/bin", "/usr/lib"]
if any(executable.startswith(p) for p in suspicious_paths):
print("\n⚠️ WARNING: you're using system Python. Check your PATH.")
else:
print("\n✓ Looks good — this Python is not the system one.")
if __name__ == "__main__":
main()
Guarda este archivo y ejecútalo con python verify_env.py. Lo que importa aquí es la ruta del ejecutable (sys.executable): si empieza por /Users/tu_usuario/.pyenv/ o /opt/homebrew/, estás usando tu Python. Si empieza por /usr/bin/, algo en tu PATH está mal configurado.
Lo que hace este código y por qué importa
sys.version_info es una tupla nombrada con los componentes de la versión — más fiable que parsear sys.version como string. sys.executable te dice exactamente qué binario está corriendo, sin ambigüedad. Y sysconfig.get_path("stdlib") revela dónde está la librería estándar, útil para confirmar que los módulos que instalas con pip van al lugar correcto y no se mezclan con los del sistema.
La verificación de rutas sospechosas es simplista pero efectiva para un diagnóstico rápido: el Python del sistema en macOS siempre vive bajo /usr/bin.
Errores que debes conocer
Error: Usar sudo pip install <paquete> instala paquetes en el Python del sistema con permisos de superusuario, mezclando dependencias de proyectos distintos y potencialmente sobrescribiendo paquetes que macOS necesita para sus propias herramientas.
# ❌ Wrong sudo pip install requests # ✅ Right pip install requests # dentro de un entorno virtual # o, si aún no tienes venv: python -m venv .venv && source .venv/bin/activate pip install requests
pip install sin sudo y dentro de un entorno virtual instala en un directorio bajo tu proyecto, completamente aislado del sistema y de otros proyectos.
Error: Añadir las líneas de pyenv init al archivo equivocado. macOS usa zsh por defecto, así que el archivo es ~/.zshrc. Si lo pones en ~/.bash_profile y tu shell es zsh, pyenv no se activa nunca y sigues viendo el Python del sistema.
# ❌ Wrong — editing the wrong file if your shell is zsh echo 'eval "$(pyenv init -)"' >> ~/.bash_profile # ✅ Right echo 'eval "$(pyenv init -)"' >> ~/.zshrc source ~/.zshrc
Puedes confirmar qué shell estás usando con echo $SHELL — si ves /bin/zsh, edita .zshrc.
Error: Instalar paquetes globalmente con el Python de Homebrew pensando que es equivalente a tener entornos aislados. brew install python te da un Python limpio, pero cada pip install sin entorno virtual sigue acumulando paquetes en un solo lugar, creando conflictos entre proyectos con dependencias incompatibles.
# ❌ Wrong — installs globally into Homebrew's Python pip3 install flask==2.0 # ✅ Right — isolated per project python3 -m venv .venv source .venv/bin/activate pip install flask==2.0
Los entornos virtuales (tema que viene en esta misma sección) son el complemento necesario tanto de Homebrew como de pyenv.
N° 8