> **Источник:** https://python-all.ru/3.15/library/sys_path_init.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Инициализация [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path) пути поиска модулей

Путь поиска модулей инициализируется при запуске Python. Этот путь поиска модулей доступен через [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path).

Первая запись в пути поиска модулей – это каталог, содержащий входной скрипт, если таковой имеется. В противном случае первой записью является текущий каталог, что бывает при использовании интерактивной оболочки, выполнении команды [`-c`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-c) или модуля [`-m`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-m).

Переменная окружения [`PYTHONPATH`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONPATH) часто используется для добавления каталогов в путь поиска. Если эта переменная окружения установлена, её содержимое добавляется в путь поиска модулей.

> **Примечание**
>
> [`PYTHONPATH`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONPATH) повлияет на все установленные версии и окружения Python. Следует проявлять осторожность при установке этого в профиле оболочки или глобальных переменных окружения. Модуль [`site`](https://python-all.ru/3.15/library/site.html#module-site) предлагает более тонкие методы, как описано ниже.

Следующими добавляются каталоги, содержащие стандартные модули Python, а также любые [модули расширения](https://python-all.ru/3.15/glossary.html#term-extension-module), от которых зависят эти модули. Модули расширения – это файлы `.pyd` в Windows и файлы `.so` на других платформах. Каталог с платформенно-независимыми модулями Python называется `prefix`. Каталог с модулями расширения называется `exec_prefix`.

Переменная окружения [`PYTHONHOME`](https://python-all.ru/3.15/using/cmdline.html#envvar-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`](https://python-all.ru/3.15/library/sys.html#sys.platlibdir) и [`PYTHONPLATLIBDIR`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONPLATLIBDIR).

После обнаружения `prefix` и `exec_prefix` доступны через [`sys.base_prefix`](https://python-all.ru/3.15/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.15/library/sys.html#sys.base_exec_prefix) соответственно.

Если [`PYTHONHOME`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONHOME) не установлена, и файл `pyvenv.cfg` найден рядом с основным исполняемым файлом или в его родительском каталоге, то [`sys.prefix`](https://python-all.ru/3.15/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.15/library/sys.html#sys.exec_prefix) устанавливаются в каталог, содержащий `pyvenv.cfg`; в противном случае они устанавливаются в то же значение, что и [`sys.base_prefix`](https://python-all.ru/3.15/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.15/library/sys.html#sys.base_exec_prefix) соответственно. Это используется [виртуальными окружениями](https://python-all.ru/3.15/library/sys_path_init.html#sys-path-init-virtual-environments).

Наконец, обрабатывается модуль [`site`](https://python-all.ru/3.15/library/site.html#module-site), и в путь поиска модулей добавляются каталоги `site-packages`. Переменная окружения [`PYTHONUSERBASE`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONUSERBASE) управляет тем, где искать пользовательские site-packages, а переменная окружения [`PYTHONNOUSERSITE`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONNOUSERSITE) полностью запрещает их поиск. Распространённый способ настройки пути поиска – создать модули [`sitecustomize`](https://python-all.ru/3.15/library/site.html#module-sitecustomize) или [`usercustomize`](https://python-all.ru/3.15/library/site.html#module-usercustomize), как описано в документации модуля `site`.

> **Примечание**
>
> Параметры командной строки [`-E`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-E), [`-P`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-P), [`-I`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-I), [`-S`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-S) и [`-s`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-s) также влияют на вычисление путей; подробнее см. в их документации.

Изменено в версии 3.14: [`sys.prefix`](https://python-all.ru/3.15/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.15/library/sys.html#sys.exec_prefix) теперь устанавливаются в каталог `pyvenv.cfg` во время инициализации пути. Ранее это выполнялось [`site`](https://python-all.ru/3.15/library/site.html#module-site), поэтому на него влияли [`-S`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-S).

## Виртуальные окружения

Виртуальные окружения помещают файл `pyvenv.cfg` в свой префикс, что заставляет [`sys.prefix`](https://python-all.ru/3.15/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.15/library/sys.html#sys.exec_prefix) указывать на них, а не на базовую установку.

Значения `prefix` и `exec_prefix` базовой установки доступны через [`sys.base_prefix`](https://python-all.ru/3.15/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.15/library/sys.html#sys.base_exec_prefix).

Помимо использования в качестве маркера для идентификации виртуальных окружений, `pyvenv.cfg` также может использоваться для настройки инициализации [`site`](https://python-all.ru/3.15/library/site.html#module-site). Обратитесь к [документации по виртуальным окружениям](https://python-all.ru/3.15/library/site.html#site-virtual-environments-configuration) `site`.

> **Примечание**
>
> [`PYTHONHOME`](https://python-all.ru/3.15/using/cmdline.html#envvar-PYTHONHOME) переопределяет обнаружение `pyvenv.cfg`.

> **Примечание**
>
> Существуют и другие способы реализации «виртуальных окружений». В этой документации рассматриваются реализации, основанные на механизме `pyvenv.cfg`, например [`venv`](https://python-all.ru/3.15/library/venv.html#module-venv), которому следуют многие реализации виртуальных окружений.

## Файлы \_pth

Чтобы полностью переопределить [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path), создайте файл `._pth` с тем же именем, что и у общей библиотеки или исполняемого файла (`python._pth` или `python311._pth`). Путь к общей библиотеке всегда известен в Windows, однако на других платформах он может быть недоступен. В файле `._pth` укажите по одной строке для каждого пути, добавляемого в `sys.path`. Файл, основанный на имени общей библиотеки, переопределяет файл, основанный на исполняемом файле, что позволяет при желании ограничить пути для любой программы, загружающей среду выполнения.

Если файл существует, все реестровые и переменные окружения игнорируются, включается изолированный режим, и [`site`](https://python-all.ru/3.15/library/site.html#module-site) не импортируется, если только одна из строк файла не указывает `import site`. Пустые пути и строки, начинающиеся с `#`, игнорируются. Каждый путь может быть абсолютным или относительным относительно расположения файла. Операторы импорта, кроме `site`, не допускаются, и произвольный код не может быть задан.

Обратите внимание, что файлы `.pth` (без ведущего подчёркивания) будут обрабатываться модулем [`site`](https://python-all.ru/3.15/library/site.html#module-site) в обычном порядке, если указан `import site`.

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

Если Python встраивается в другое приложение, [`Py_InitializeFromConfig()`](https://python-all.ru/3.15/c-api/interp-lifecycle.html#c.Py_InitializeFromConfig) и структура [`PyConfig`](https://python-all.ru/3.15/c-api/init_config.html#c.PyConfig) могут использоваться для инициализации Python. Подробности, касающиеся пути, описаны в [конфигурации пути поиска Python](https://python-all.ru/3.15/c-api/init_config.html#init-path-config).

> **См. также**
>
> - [Поиск модулей](https://python-all.ru/3.15/using/windows.html#windows-finding-modules) для подробных замечаний по Windows.
> - [Использование Python на платформах Unix](https://python-all.ru/3.15/using/unix.html#using-on-unix) для подробностей по Unix.