Cómo configurar PYTHONPATH en Windows, macOS y Linux (Variables de entorno)

PYTHONPATH es una variable de entorno que extiende sys.path (donde Python busca módulos al hacer import). Permite importar paquetes locales sin instalarlos (pip install -e .) ni moverlos a site-packages. Útil para desarrollo, testing, monorepos y scripts.

Windows 11 / 10 / 8 / 7

Método 1: GUI (Interfaz gráfica) - Permanente, usuario o sistema

1. Win → busque "Editar las variables de entorno del sistema" / "Edit the system environment variables" → Enter.
2. Botón Variables de entorno... (abajo).
3. En Variables de usuario (solo su usuario) o Variables del sistema (todos, requiere admin):
   Nueva...
   Nombre: PYTHONPATH
   Valor: C:\ruta\a\su\proyecto;C:\otra\ruta\modulos (separados por punto y coma ;)
4. Aceptar ×3. Reinicie terminales abiertas para tomar efecto.

Método 2: PowerShell (Temporal / Sesión actual)

$env:PYTHONPATH = "C:\ruta\a\proyecto;C:\otra\ruta"
# Verificar:
python -c "import sys; print('\n'.join(sys.path))"

Para permanente en PowerShell (perfil usuario):

notepad $PROFILE
# Añada línea:
[Environment]::SetEnvironmentVariable("PYTHONPATH", "C:\ruta\a\proyecto;C:\otra\ruta", "User")

Método 3: Command Prompt (cmd) - Temporal

set PYTHONPATH=C:\ruta\a\proyecto;C:\otra\ruta
python -c "import sys; print(sys.path)"

Permanente (usuario): setx PYTHONPATH "C:\ruta\a\proyecto;C:\otra\ruta" (requiere nueva ventana).

macOS / Linux (bash, zsh, fish)

bash (~/.bashrc) / zsh (~/.zshrc) - Permanente, usuario

1. Edite archivo: nano ~/.bashrc o nano ~/.zshrc.
2. Añada al final:
   

   export PYTHONPATH="${PYTHONPATH}:/ruta/a/su/proyecto:/otra/ruta/modulos"
   

   Usar : como separador (no ;). ${PYTHONPATH} preserva valores existentes.
3. source ~/.bashrc o source ~/.zshrc (o reinicie terminal).

fish (~/.config/fish/config.fish)

set -gx PYTHONPATH $PYTHONPATH /ruta/a/su/proyecto /otra/ruta/modulos

Temporal (sesión actual)

export PYTHONPATH="${PYTHONPATH}:/ruta/a/proyecto"  # bash/zsh
set -gx PYTHONPATH $PYTHONPATH /ruta/a/proyecto      # fish

Verificar que funciona

python -c "import sys; print('PYTHONPATH activo:'); [print(f'  {p}') for p in sys.path if 'su_proyecto' in p]"
# O simplemente:
python -c "import su_modulo; print('Import OK:', su_modulo.__file__)"

Buenas prácticas y alternativas modernas (¡Lea esto!)

Errores comunes

• Separador incorrecto: ; en Windows, : en Unix/macOS.
• Rutas relativas: Use rutas absolutas. PYTHONPATH=./src falla si cwd cambia.
• Sobrescribir en lugar de extender: Siempre ${PYTHONPATH}:nueva_ruta (Unix) / %PYTHONPATH%;nueva_ruta (Win).
• Conflicto de nombres: Si PYTHONPATH tiene proyecto/utils y site-packages tiene utils, gana el primero en sys.path. Orden importa.
• Olvidar reiniciar terminal/IDE tras cambio permanente. VS Code: Ctrl+Shift+P → "Developer: Reload Window".

Python 3.11+ : PYTHONSAFEPATH

Nueva variable: PYTHONSAFEPATH=1 ignora PYTHONPATH y site-packages de usuario para aislamiento estricto (útil en contenedores, despliegues).

Resumen rápido

# Windows (PowerShell permanente)
[Environment]::SetEnvironmentVariable("PYTHONPATH", "C:\proyecto\src;C:\libs", "User")

# macOS/Linux (bash/zsh permanente)
echo 'export PYTHONPATH="${PYTHONPATH}:/home/usuario/proyecto/src:/home/usuario/libs"' >> ~/.bashrc
source ~/.bashrc

# Verificar
python -c "import sys; print('\n'.join(sys.path))"