# 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

Si Python está embebido dentro de otra aplicación `Py_InitializeFromConfig()` y la estructura `PyConfig` pueden utilizarse para inicializar Python. Los detalles específicos de la ruta se describen en Configuración de la ruta de Python. Alternativamente se puede utilizar la antigua `Py_SetPath()` para saltarse la inicialización de la ruta de búsqueda de módulo.

Ver también

- Encontrar módulos para las notas detalladas de Windows.

- Uso de Python en plataformas Unix para los detalles de Unix.