Инициализация пути поиска модуля 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.
См.также
Поиск модулей для получения подробных заметок о Windows.
Использование Python на платформах Unix для деталей Unix.