Инициализация пути поиска модулей sys.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. Распространённый способ настроить путь поиска — создать модули sitecustomize или usercustomize, как описано в документации модуля site.