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

---

# 29.5. `runpy` – Поиск и выполнение модулей Python

Модуль `runpy` используется для поиска и запуска модулей Python без их предварительного импорта. Основное его применение – реализация флага командной строки *-m*, который позволяет искать скрипты по пространству имён модулей Python, а не по файловой системе.

При запуске в качестве скрипта модуль работает следующим образом:

```python
del sys.argv[0]  # Удалить модуль runpy из аргументов
run_module(sys.argv[0], run_name="__main__", alter_sys=True)
```

Модуль `runpy` предоставляет одну функцию:

#### `runpy.run_module(mod_name[, init_globals][, run_name][, alter_sys])`

Выполняет код указанного модуля и возвращает результирующий словарь глобальных переменных модуля. Код модуля сначала находится с помощью стандартного механизма импорта (подробности см. в PEP 302), а затем выполняется в новом пространстве имён модуля.

Если указанное имя модуля ссылается на пакет, а не на обычный модуль, то этот пакет импортируется, а затем выполняется подмодуль `__main__` внутри этого пакета, и возвращается результирующий словарь глобальных переменных модуля.

Необязательный аргумент-словарь *init\_globals* может использоваться для предварительного заполнения словаря глобальных переменных перед выполнением кода. Переданный словарь не будет изменён. Если в переданном словаре определены какие-либо из перечисленных ниже специальных глобальных переменных, эти определения переопределяются функцией `run_module`.

Специальные глобальные переменные `__name__`, `__file__`, `__loader__`, `__builtins__` и `__package__` устанавливаются в словаре глобальных переменных перед выполнением кода модуля.

`__name__` устанавливается в *run\_name*, если передан этот необязательный аргумент, в `mod_name + '.__main__'`, если именованный модуль является пакетом, и в аргумент *mod\_name* в противном случае.

`__loader__` устанавливается в загрузчик модуля PEP 302, используемый для получения кода модуля (этот загрузчик может быть обёрткой вокруг стандартного механизма импорта).

`__file__` устанавливается в имя, предоставленное загрузчиком модуля. Если загрузчик не предоставляет информацию об имени файла, эта переменная устанавливается в `None`.

`__builtins__` автоматически инициализируется ссылкой на пространство имён верхнего уровня модуля [`builtins`](https://python-all.ru/3.1/library/builtins.html#module-builtins).

`__package__` устанавливается в *mod\_name*, если именованный модуль является пакетом, и в `mod_name.rpartition('.')[0]` в противном случае.

Если аргумент *alter\_sys* передан и равен `True`, то `sys.argv[0]` обновляется значением `__file__`, а `sys.modules[__name__]` обновляется временным объектом модуля для выполняемого модуля. Оба значения `sys.argv[0]` и `sys.modules[__name__]` восстанавливаются до исходных перед возвратом из функции.

Обратите внимание, что такие манипуляции с [`sys`](https://python-all.ru/3.1/library/sys.html#module-sys) не являются потокобезопасными. Другие потоки могут увидеть частично инициализированный модуль, а также изменённый список аргументов. Рекомендуется не трогать модуль [`sys`](https://python-all.ru/3.1/library/sys.html#module-sys) при вызове этой функции из многопоточного кода.

Изменено в версии 3.1: Добавлена возможность выполнять пакеты путём поиска подмодуля `__main__`.

> **См. также**
>
> **[**PEP 338**](https://python-all.ru/3.1/library/runpy.html) – Выполнение модулей как сценариев**
>
> PEP написан и реализован Ником Когланом.
>
> **[**PEP 366**](https://python-all.ru/3.1/library/runpy.html) – Явные относительные импорты главного модуля**
>
> PEP написан и реализован Ником Когланом.