site en Python: entiende las rutas

El módulo site en Python participa en el inicio del intérprete y configura rutas específicas de la instalación. Añade directorios site-packages a sys.path, procesa archivos .pth, intenta importar sitecustomize y usercustomize y ayuda a configurar historial y autocompletado en sesiones interactivas.

Estas acciones explican por qué los paquetes instalados pueden importarse y por qué dos ejecuciones de la misma versión de Python pueden mostrar rutas diferentes. También crean una superficie sensible: las líneas ejecutables de archivos .pth se ejecutan en cada inicio y los módulos de personalización pueden ejecutar código antes de que comience la aplicación.

Import automático durante el inicio

Python normalmente importa site de forma automática. La opción -S desactiva esa etapa.

python -S -c "import sys; print(sys.path)"

Con -S, no se añaden directorios site-specific ni algunos builtins auxiliares. Desde Python 3.14, sys.prefix y sys.exec_prefix de los entornos virtuales se configuran durante la inicialización de rutas y ya no dependen del módulo site.

Llamar site.main() explícitamente

Si el intérprete comenzó con -S, importar site no aplica automáticamente todas las modificaciones normales. Para solicitarlas, llama site.main().

import site
site.main()

Las bibliotecas no deberían hacerlo. Cambiar sys.path en runtime es una operación global y puede sorprender a otros componentes. La decisión pertenece al entry point de la aplicación.

Cómo se construyen los directorios

El módulo combina prefijos como sys.prefix y sys.exec_prefix con sufijos específicos de plataforma. En Unix, una ruta típica es lib/pythonX.Y/site-packages; en Windows, suele ser Lib/site-packages.

Los builds free-threaded pueden incluir el sufijo t, como python3.13t. No construyas estas rutas manualmente. Usa funciones del módulo o sysconfig en Python.

Consultar site-packages globales

getsitepackages() devuelve los directorios globales reconocidos.

import site

for ruta in site.getsitepackages():
    print(ruta)

Instalaciones embebidas o inusuales pueden comportarse de otra manera. Las herramientas portables deben aceptar resultados vacíos y respetar el entorno virtual activo.

Consultar el user site

getusersitepackages() devuelve el directorio de paquetes del usuario.

import site

print(site.getusersitepackages())
print(site.ENABLE_USER_SITE)

Una ruta calculada no demuestra que haya sido añadida a sys.path. Consulta ENABLE_USER_SITE.

Interpretar ENABLE_USER_SITE

La flag tiene tres estados importantes:

• True: habilitado y añadido a la ruta.
• False: deshabilitado por el usuario mediante -s o PYTHONNOUSERSITE.
• None: deshabilitado por seguridad o por el administrador.

No conviertas simplemente el valor con bool() cuando necesites distinguir preferencia y política de seguridad.

Deshabilitar paquetes del usuario

La opción -s desactiva el user site:

python -s -c "import site; print(site.ENABLE_USER_SITE)"

PYTHONNOUSERSITE ofrece un comportamiento similar. Servicios, tareas programadas y entornos reproducibles suelen beneficiarse de excluir paquetes personales.

USER_BASE y PYTHONUSERBASE

getuserbase() devuelve la base usada por el esquema de instalación del usuario. PYTHONUSERBASE puede sustituir el valor predeterminado.

import site

print(site.getuserbase())
print(site.USER_BASE)

Cambiar esta variable afecta dónde se instalan scripts, módulos y datos del usuario. Defínela antes de iniciar Python y documéntala en pipelines.

Usar python -m site

La interfaz de línea de comandos imprime sys.path, user base, user site y estado de habilitación.

python -m site
python -m site --user-base
python -m site --user-site

Cuando se usan opciones de directorios del usuario, el código de salida indica si el user site está habilitado, deshabilitado por el usuario o bloqueado por seguridad.

Archivos de configuración .pth

Los archivos terminados en .pth dentro de directorios site se procesan en orden alfabético. Las líneas normales añaden rutas existentes a sys.path. Líneas vacías y comentarios se ignoran.

# ejemplo.pth
/opt/mi_app/libs
/opt/mi_app/plugins

Las rutas inexistentes se omiten y los duplicados se evitan. No es obligatorio que la entrada sea un directorio; un archivo existente también puede añadirse.

El orden alfabético importa

Los nombres de archivo determinan el orden de procesamiento, lo que puede modificar la precedencia de imports. Si el mismo nombre existe en dos ubicaciones, la posición final en sys.path decide cuál se carga.

Evita trucos no documentados como 00-primero.pth. Prefiere venvs limpios e instalaciones normales.

Líneas ejecutables en .pth

Una línea que comienza con import o import se ejecuta en cada inicio.

import mi_hook_de_inicio

Esto ocurre aunque la aplicación nunca use el paquete relacionado. La restricción a una línea es deliberada y desaconseja lógica compleja.

Riesgo de seguridad

Quien pueda escribir en un directorio site-packages puede obtener ejecución persistente en cada proceso Python que utilice el entorno. Protege permisos y trata los archivos .pth como configuración ejecutable.

from pathlib import Path
import site

for directorio in site.getsitepackages():
    for archivo in Path(directorio).glob('*.pth'):
        print(archivo)
        for linea in archivo.read_text(errors='replace').splitlines():
            if linea.startswith(('import ', 'import\t')):
                print('  ejecuta:', linea)

Encoding de los .pth

Desde Python 3.13, site intenta decodificar los archivos primero como UTF-8 y luego con el encoding de la locale. Usa UTF-8 y evita caracteres innecesarios en rutas de infraestructura.

Añadir un directorio con addsitedir()

addsitedir() añade un directorio y procesa sus archivos .pth.

import site

site.addsitedir('/opt/mi_app/site-packages')

La operación modifica globalmente la ruta de imports y puede ejecutar líneas. Nunca pases una ruta no confiable. Los sistemas de plugins deberían preferir instalación controlada y reinicio del proceso.

sitecustomize

Después de procesar rutas, Python intenta importar sitecustomize. Los administradores pueden usarlo para políticas globales pequeñas, audit hooks, encoding o configuración corporativa.

Si el módulo no existe, se ignora el ImportError específico. Otras excepciones pueden provocar fallos confusos durante el inicio. Mantén el módulo pequeño, probado e independiente de servicios frágiles.

usercustomize

Cuando el user site está habilitado, Python intenta importar usercustomize desde el directorio del usuario.

Puede personalizar sesiones interactivas confiables, pero las aplicaciones no deberían depender de él. Los servicios de producción suelen deshabilitar el user site.

No imprimir durante el startup

La salida de módulos de personalización puede corromper protocolos, herramientas que generan JSON y CLIs. Con pythonw.exe, la salida puede descartarse.

Registra solo cuando esté habilitado explícitamente y usa un destino protegido.

Configuración automática de readline

En modo interactivo, sin -S, site configura rlcompleter e historial cuando readline está disponible. El archivo de historial suele ser ~/.python_history.

Para comprender autocompletado y efectos de atributos dinámicos, consulta rlcompleter en Python.

Deshabilitar el hook interactivo

sys.__interactivehook__ controla esa configuración. Una personalización puede eliminarlo.

import sys

if hasattr(sys, '__interactivehook__'):
    del sys.__interactivehook__

Hazlo solo cuando controles la experiencia interactiva. Una biblioteca no debería modificar el hook global.

Entornos virtuales y pyvenv.cfg

pyvenv.cfg puede incluir include-system-site-packages = true. Cuando es falso, el venv excluye paquetes globales.

Para proyectos reproducibles, mantenlo falso e instala cada dependencia dentro del entorno. Los paquetes globales pueden ocultar requisitos no declarados.

Comprobar prefijos del venv

import sys

print('prefix:', sys.prefix)
print('base_prefix:', sys.base_prefix)
print('venv:', sys.prefix != sys.base_prefix)

En Python 3.14, estos valores siguen siendo correctos incluso con -S.

site o sysconfig

Usa site para inspeccionar directorios activos, estado del user site y personalización de inicio. Usa sysconfig para esquemas estructurados de instalación y build.

No deduzcas reglas multiplataforma a partir de una sola ruta observada.

Diagnosticar un import inesperado

import modulo
import sys

print(modulo.__file__)
print('\n'.join(sys.path))

Después examina archivos .pth, PYTHONPATH, user site, venv y módulos de personalización. pkgutil en Python puede listar módulos disponibles.

Interacción con PYTHONPATH

PYTHONPATH influye en rutas antes de varias operaciones de site. Un valor global puede afectar todos los entornos Python.

Evita definirlo permanentemente en todo el sistema. Prefiere una instalación editable controlada o configuración del venv.

Modo aislado con -I

La opción -I ignora variables PYTHON* y deshabilita el user site, entre otras protecciones.

python -I -c "import sys; print(sys.path)"

Es útil para herramientas administrativas menos influenciadas por el entorno del usuario, aunque las personalizaciones globales de la instalación todavía deben revisarse.

Probar sitecustomize de forma segura

Usa un venv temporal, coloca el módulo en su site-packages y lanza un subprocesso.

import subprocess

resultado = subprocess.run(
    ['.venv/bin/python', '-c', 'print("ok")'],
    text=True,
    capture_output=True,
    check=True,
)
assert resultado.stdout.strip() == 'ok'

Prueba inicio normal, -S, -s, errores y ausencia de streams. No experimentes en Python global.

Auditar diferencias de inicio

python -m site
python -s -m site
python -S -c "import sys; print(sys.path)"
python -I -m site

Las diferencias muestran el efecto de user site, del módulo site y del modo aislado.

Errores frecuentes

• Añadir rutas del usuario con addsitedir().
• Colocar lógica compleja en una línea de .pth.
• Usar sitecustomize como sistema de plugins.
• Imprimir en stdout durante el inicio.
• Depender de paquetes globales dentro de un venv.
• Confundir user site existente con habilitado.
• Construir rutas site-packages manualmente.

Buenas prácticas

• Usa venvs limpios y reproducibles.
• Protege permisos de site-packages.
• Audita líneas ejecutables en .pth.
• Mantén personalizaciones mínimas.
• Deshabilita user site en servicios.
• Usa sysconfig para rutas estructuradas.
• Prueba el inicio en subprocessos.

Conclusión

El módulo site en Python explica buena parte de la configuración automática de imports: directorios site-packages, archivos .pth, paquetes del usuario y hooks de personalización.

Esta comodidad se ejecuta antes de la aplicación y exige control estricto. Protege directorios, evita lógica compleja y usa entornos virtuales. Consulta la documentación oficial del módulo site y la documentación de inicialización de sys.path.