Nota
¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.
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 yPYTHONHOME
no está establecido, esta ruta se utiliza en lugar de la ruta al ejecutable principal cuando se deduceprefix
yexec_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.