La inicialización de la ruta de búsqueda de módulo de sys.path

Una ruta de búsqueda de módulo se inicializa cuando se inicia Python. Se puede acceder a esta ruta de búsqueda de módulo en sys.path.

La primera entrada en la ruta de búsqueda de módulo es el directorio que contiene el script de entrada, si lo hay. De lo contrario, la primera entrada es el directorio actual, que es el caso cuando se ejecuta el shell interactivo, un comando -c o un módulo -m.

La variable de entorno PYTHONPATH se utiliza a menudo para añadir directorios a la ruta de búsqueda. Si se encuentra esta variable de entorno, su contenido se añade a la ruta de búsqueda del módulo.

Nota

PYTHONPATH afectará a todas las versiones/entornos de Python instalados. Tenga cuidado al establecer esto en su perfil de shell o en las variables de entorno globales. El módulo site ofrece técnicas más suavizadas como se menciona a continuación.

Los siguientes elementos que se añaden son los directorios que contienen los módulos estándar de Python, así como los extension module de los que dependen estos módulos. Los módulos de extensión son archivos .pyd en Windows y archivos .so en otras plataformas. El directorio con los módulos Python independientes de la plataforma se llama prefix. El directorio con los módulos de extensión se llama exec_prefix.

La variable de entorno PYTHONHOME puede utilizarse para establecer las ubicaciones prefix y exec_prefix. De lo contrario, estos directorios se encuentran utilizando el ejecutable de Python como punto de partida y luego buscando varios archivos y directorios «de referencia». Tenga en cuenta que cualquier enlace simbólico se sigue, por lo que la ubicación real del ejecutable de Python se utiliza como punto de partida de la búsqueda. La ubicación del ejecutable de Python se llama home.

Una vez determinado home, el directorio prefix se encuentra buscando primero pythonmajorversionminorversion.zip (python311.zip). En Windows el archivo zip se busca en home y en Unix se espera que el archivo esté en lib. Tenga en cuenta que la ubicación esperada del archivo zip se añade a la ruta de búsqueda del módulo incluso si el archivo no existe. Si no se encuentra ningún archivo, Python en Windows continuará la búsqueda de prefix buscando en Lib\os.py. Python en Unix buscará lib/pythonmajorversion.minorversion/os.py (lib/python3.11/os.py). En Windows prefix y prefix_exec son los mismos, sin embargo en otras plataformas se busca lib/pythonmajorversion.minorversion/lib-dynload (lib/python3.11/lib-dynload) y se utiliza como ancla para prefix_exec. En algunas plataformas lib puede ser lib64 u otro valor, ver sys.platlibdir y PYTHONPLATLIBDIR.

Una vez encontrados, prefix y exec_prefix están disponibles en sys.prefix y sys.exec_prefix respectivamente.

Finalmente, el módulo site se procesa y los directorios site-packages se añaden a la ruta de búsqueda de módulo. Una forma común de personalizar la ruta de búsqueda es crear módulos sitecustomize o usercustomize como se describe en la documentación del módulo site.

Nota

Ciertas opciones de la línea de comandos pueden afectar aún más los cálculos de ruta. Vea -E, -I, -s y -S para más detalles.

Entornos virtuales

Si Python se ejecuta en un entorno virtual (como se describe en Entornos virtuales y paquetes) entonces prefix y exec_prefix son específicos del entorno virtual.

Si se encuentra un archivo pyvenv.cfg junto al ejecutable principal, o en el directorio un nivel por encima del ejecutable, se aplican las siguientes variaciones:

  • Si home es una ruta absoluta y PYTHONHOME no está establecido, esta ruta se utiliza en lugar de la ruta al ejecutable principal cuando se deduce prefix y exec_prefix.

Archivos _pth

Para anular completamente sys.path cree un archivo ._pth con el mismo nombre que la biblioteca compartida o el ejecutable (python._pth o python311._pth). La ruta de la biblioteca compartida se conoce siempre en Windows, pero puede no estar disponible en otras plataformas. En el archivo ._pth especifique una línea por cada ruta a añadir a sys.path`. El archivo basado en el nombre de la biblioteca compartida anula el basado en el ejecutable, lo que permite restringir las rutas para cualquier programa en tiempo de ejecución si se desea.

Cuando el archivo existe, se ignoran todas las variables de registro y de entorno, se habilita el modo aislado y no se importa site a menos que una línea del archivo especifique import site. Las rutas en blanco y las líneas que comienzan con # son ignoradas. Cada ruta puede ser absoluta o relativa a la ubicación del fichero. No se permiten declaraciones de importación distintas de site, y no se puede especificar código arbitrario.

Tenga en cuenta que los archivos .pth (sin guión bajo inicial) serán procesados normalmente por el módulo site cuando se haya especificado import site.

Python embebido

If Python is embedded within another application Py_InitializeFromConfig() and the PyConfig structure can be used to initialize Python. The path specific details are described at Configuración de la ruta de Python.

Ver también