Инициализация sys.path пути поиска модулей¶The initialization of the sys.path module search path

Путь поиска модулей инициализируется при запуске Python. Этот путь поиска модулей доступен через sys.path.

Первая запись в пути поиска модулей – это каталог, содержащий входной скрипт, если таковой имеется. В противном случае первой записью является текущий каталог, что бывает при использовании интерактивной оболочки, выполнении команды -c или модуля -m.

Переменная окружения PYTHONPATH часто используется для добавления каталогов в путь поиска. Если эта переменная окружения установлена, её содержимое добавляется в путь поиска модулей.

Следующими добавляются каталоги, содержащие стандартные модули Python, а также любые модули расширения, от которых зависят эти модули. Модули расширения – это файлы .pyd в Windows и файлы .so на других платформах. Каталог с платформенно-независимыми модулями Python называется prefix. Каталог с модулями расширения называется exec_prefix.

Переменная окружения PYTHONHOME может использоваться для задания расположения prefix и exec_prefix. В противном случае эти каталоги находятся с использованием исполняемого файла Python в качестве отправной точки и последующего поиска различных «опознавательных» файлов и каталогов. Обратите внимание, что символические ссылки разрешаются, поэтому в качестве начальной точки поиска используется реальное расположение исполняемого файла Python. Расположение исполняемого файла Python называется home.

После определения home каталог prefix находится путём первоначального поиска pythonmajorversionminorversion.zip (python311.zip). В Windows zip-архив ищется в home, а в Unix архив ожидается в lib. Обратите внимание, что ожидаемое расположение zip-архива добавляется в путь поиска модулей, даже если архив не существует. Если архив не найден, Python в Windows продолжит поиск prefix, разыскивая Lib\os.py. Python в Unix будет искать lib/pythonmajorversion.minorversion/os.py (lib/python3.11/os.py). В Windows prefix и exec_prefix совпадают, однако на других платформах lib/pythonmajorversion.minorversion/lib-dynload (lib/python3.11/lib-dynload) ищется и используется как привязка для exec_prefix. На некоторых платформах lib может быть lib64 или другим значением, см. sys.platlibdir и PYTHONPLATLIBDIR.

После обнаружения prefix и exec_prefix доступны через sys.base_prefix и sys.base_exec_prefix соответственно.

Если PYTHONHOME не установлена, и файл pyvenv.cfg найден рядом с основным исполняемым файлом или в его родительском каталоге, то sys.prefix и sys.exec_prefix устанавливаются в каталог, содержащий pyvenv.cfg; в противном случае они устанавливаются в то же значение, что и sys.base_prefix и sys.base_exec_prefix соответственно. Это используется виртуальными окружениями.

Наконец, обрабатывается модуль site, и в путь поиска модулей добавляются каталоги site-packages. Переменная окружения PYTHONUSERBASE управляет тем, где искать пользовательские site-packages, а переменная окружения PYTHONNOUSERSITE полностью запрещает их поиск. Распространённый способ настройки пути поиска – создать модули sitecustomize или usercustomize, как описано в документации модуля site.