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.

Once found, prefix and exec_prefix are available at sys.base_prefix and sys.base_exec_prefix respectively.

If PYTHONHOME is not set, and a pyvenv.cfg file is found alongside the main executable, or in its parent directory, sys.prefix and sys.exec_prefix get set to the directory containing pyvenv.cfg, otherwise they are set to the same value as sys.base_prefix and sys.base_exec_prefix, respectively. This is used by Virtual Environments.

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.

Distinto en la versión 3.14: sys.prefix and sys.exec_prefix are now set to the pyvenv.cfg directory during the path initialization. This was previously done by site, therefore affected by -S.

Virtual Environments

Virtual environments place a pyvenv.cfg file in their prefix, which causes sys.prefix and sys.exec_prefix to point to them, instead of the base installation.

The prefix and exec_prefix values of the base installation are available at sys.base_prefix and sys.base_exec_prefix.

As well as being used as a marker to identify virtual environments, pyvenv.cfg may also be used to configure the site initialization. Please refer to site’s virtual environments documentation.

Nota

PYTHONHOME overrides the pyvenv.cfg detection.

Nota

There are other ways how «virtual environments» could be implemented, this documentation referes implementations based on the pyvenv.cfg mechanism, such as venv. Most virtual environment implementations follow the model set by venv, but there may be exotic implementations that diverge from it.

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