Инициализация пути поиска модуля sys.path

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

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

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

Примечание

PYTHONPATH будет влиять на все установленные версии/окружения Python. Остерегайтесь устанавливать это значение в профиле оболочки или глобальных переменных окружения. Модуль site предлагает более тонкие техники, о которых говорится ниже.

Следующими добавляются каталоги, содержащие стандартные модули Python, а также все extension modules, от которых эти модули зависят. Модули расширения представляют собой файлы .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.prefix и sys.exec_prefix соответственно.

Наконец, модуль site обрабатывается, а каталоги site-packages добавляются в путь поиска модуля. Обычно путь поиска настраивается путем создания модулей sitecustomize или usercustomize, как описано в документации по модулю site.

Примечание

Некоторые параметры командной строки могут дополнительно влиять на вычисление пути. Дополнительные сведения см. в разделах -E, -I, -s и -S.

Виртуальные среды

Если Python выполняется в виртуальной среде (как описано в Виртуальные среды и пакеты), то prefix и exec_prefix специфичны для виртуальной среды.

Если файл pyvenv.cfg найден рядом с основным исполняемым файлом или в каталоге, расположенном на один уровень выше исполняемого файла, применяются следующие варианты:

  • Если home является абсолютным путем и PYTHONHOME не задан, то этот путь используется вместо пути к основному исполняемому файлу при вычислении prefix и exec_prefix.

_pth файлы

Чтобы полностью отменить sys.path, создайте файл ._pth с тем же именем, что и общая библиотека или исполняемый файл (python._pth или python311._pth). Путь к общей библиотеке всегда известен в Windows, однако на других платформах он может быть недоступен. В файле ._pth укажите по одной строке для каждого пути, который нужно добавить в sys.path. Файл, основанный на имени разделяемой библиотеки, переопределяет файл, основанный на исполняемом файле, что позволяет при желании ограничить пути для любой программы, загружающей среду выполнения.

Когда файл существует, все переменные реестра и окружения игнорируются, включается изолированный режим, и site не импортируется, если в одной из строк файла не указано import site. Пустые пути и строки, начинающиеся с #, игнорируются. Каждый путь может быть абсолютным или относительным по отношению к местоположению файла. Операторы импорта, отличные от site, не допускаются, и произвольный код не может быть указан.

Обратите внимание, что файлы .pth (без ведущего подчеркивания) будут нормально обрабатываться модулем site, если указан import site.

Встраиваемый Python

Если Python встроен в другое приложение, то для инициализации Python можно использовать структуру Py_InitializeFromConfig() и PyConfig. Конкретные детали пути описаны в Конфигурация пути Python.

См.также