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

---

# Установка модулей Python (устаревшая версия)

**Автор**

Greg Ward

> **См. также**
>
> **[Установка модулей Python](https://python-all.ru/3.7/installing/index.html#installing-index)**
>
> Актуальная документация по установке модулей

В этом документе описываются утилиты распространения Python (Distutils) с точки зрения конечного пользователя: как расширить возможности стандартной установки Python, собрав и установив сторонние модули и расширения Python.

> **Примечание**
>
> Это руководство охватывает только основные инструменты для сборки и распространения расширений, входящие в состав этой версии Python. Сторонние инструменты предлагают более простые и безопасные альтернативы. Для получения дополнительной информации обратитесь к [разделу с краткими рекомендациями](https://python-all.ru/3.7/install/index.html) в руководстве пользователя по упаковке Python.

## Введение

Хотя обширная стандартная библиотека Python покрывает многие потребности программирования, часто наступает момент, когда необходимо добавить новую функциональность в установку Python в виде сторонних модулей. Это может понадобиться для поддержки собственных программ или для использования приложения, написанного на Python.

В прошлом было мало поддержки для добавления сторонних модулей в существующую установку Python. С появлением утилит распространения Python (сокращённо Distutils) в Python 2.0 это изменилось.

Этот документ предназначен в первую очередь для тех, кому нужно установить сторонние модули Python: конечных пользователей и системных администраторов, которым просто нужно запустить какое-нибудь Python-приложение, а также опытных программистов Python, желающих добавить новые инструменты в свой арсенал. Для чтения этого документа не требуется знать Python; будут лишь краткие экскурсы в интерактивный режим Python для изучения вашей установки, но не более. Если вы ищете информацию о том, как распространять собственные модули Python, чтобы другие могли их использовать, обратитесь к руководству [Distributing Python Modules (Legacy version)](https://python-all.ru/3.7/distutils/index.html#distutils-index). Также может быть полезна [отладка сценария установки](https://python-all.ru/3.7/distutils/setupscript.html#debug-setup-script).

### Идеальный случай: простая установка

В идеальном случае кто-то подготовит специальную версию распространяемого модуля, который вы хотите установить, ориентированную именно на вашу платформу, и устанавливаемую как любое другое программное обеспечение на вашей платформе. Например, разработчик модуля может предоставить исполняемый установщик для пользователей Windows, пакет RPM для пользователей Linux-систем на основе RPM (Red Hat, SuSE, Mandrake и многих других), пакет Debian для пользователей систем на основе Debian и так далее.

В этом случае вы загрузите установщик, подходящий для вашей платформы, и сделаете очевидное: запустите его, если это исполняемый установщик, `rpm --install` его, если это RPM, и т.д. Вам не нужно запускать Python или сценарий установки, не нужно ничего компилировать – возможно, вам даже не придётся читать какие-либо инструкции (хотя всегда полезно это сделать).

Конечно, не всегда всё так просто. Возможно, вас заинтересует распространяемый модуль, для которого нет простого установщика для вашей платформы. В этом случае придётся начать с исходного дистрибутива, выпущенного автором или сопровождающим модуля. Установка из исходного дистрибутива не слишком сложна, если модули упакованы стандартным образом. Основная часть этого документа посвящена сборке и установке модулей из стандартных исходных дистрибутивов.

### Новый стандарт: Distutils

Если вы загружаете исходный дистрибутив модуля, можно довольно быстро понять, был ли он упакован и распространён стандартным способом, то есть с помощью Distutils. Во-первых, имя дистрибутива и номер версии будут чётко указаны в имени загружаемого архива, например, `foo-1.0.tar.gz` или `widget-0.9.7.zip`. Затем архив распакуется в каталог с похожим именем: `foo-1.0` или `widget-0.9.7`. Кроме того, дистрибутив будет содержать скрипт установки `setup.py` и файл с именем `README.txt` или возможно просто `README`, в котором будет объяснено, что сборка и установка дистрибутива модуля сводится к выполнению одной команды в терминале:

```text
python setup.py install
```

Для Windows эту команду следует запускать из окна командной строки (Пуск ‣ Стандартные):

```text
setup.py install
```

Если всё это верно, то вы уже знаете, как собрать и установить только что загруженные модули: просто выполните указанную выше команду. Если вам не нужно устанавливать что-либо нестандартным способом или настраивать процесс сборки, эта документация вам по большому счёту не понадобится. Вернее, приведённая выше команда – это всё, что нужно, чтобы обойтись без этого руководства.

## Стандартная сборка и установка

Как описано в разделе [Новый стандарт: Distutils](https://python-all.ru/3.7/install/index.html#inst-new-standard), сборка и установка распространяемого модуля с помощью Distutils обычно сводится к одной простой команде, выполняемой из терминала:

```text
python setup.py install
```

### Различия по платформам

Команду setup всегда следует выполнять из корневого каталога дистрибутива, то есть из каталога верхнего уровня, в который распакован дистрибутив исходных кодов модуля. Например, если вы только что загрузили дистрибутив исходных кодов модуля `foo-1.0.tar.gz` в системе Unix, обычные действия таковы:

```text
gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install
```

В Windows вы, вероятно, загрузите `foo-1.0.zip`. Если архивный файл загружен в `C:\Temp`, то он распакуется в `C:\Temp\foo-1.0`. Для распаковки архива можно использовать программу с графическим интерфейсом (например, WinZip) или утилиту командной строки (например, **unzip** или **pkunzip**). Затем откройте окно командной строки и выполните:

```text
cd c:\Temp\foo-1.0
python setup.py install
```

### Разделение процесса на этапы

Запуск `setup.py install` собирает и устанавливает все модули за один раз. Если вы предпочитаете работать поэтапно – это особенно полезно при настройке процесса сборки или при возникновении проблем – вы можете использовать сценарий setup для выполнения по одной задаче за раз. Это особенно удобно, когда сборка и установка выполняются разными пользователями: например, вы можете собрать дистрибутив модуля и передать его системному администратору для установки (или установить самостоятельно, имея права суперпользователя).

Например, можно выполнить сборку на первом шаге, а установку – на втором, вызвав сценарий setup дважды:

```text
python setup.py build
python setup.py install
```

Если вы так сделаете, то заметите, что команда **install** сначала запускает команду **build**, которая в этом случае быстро обнаруживает, что ей ничего не нужно делать, так как всё в каталоге `build` уже актуально.

Возможно, разбиение на этапы не понадобится, если вы только устанавливаете модули, загруженные из сети, но это очень удобно для более сложных задач. Если вы начнёте распространять собственные модули и расширения Python, вам придётся часто запускать отдельные команды Distutils самостоятельно.

### Как работает сборка

Как уже было сказано, команда **build** отвечает за помещение устанавливаемых файлов в *каталог сборки*. По умолчанию это `build` в корне дистрибутива; если вы слишком обеспокоены скоростью или хотите сохранить исходное дерево в чистоте, вы можете изменить каталог сборки с помощью опции `--build-base`. Например:

```text
python setup.py build --build-base=/path/to/pybuild/foo-1.0
```

(Или это можно сделать постоянно с помощью директивы в системном или личном конфигурационном файле Distutils; см. раздел [Конфигурационные файлы Distutils](https://python-all.ru/3.7/install/index.html#inst-config-files).) Обычно в этом нет необходимости.

Структура дерева сборки по умолчанию выглядит следующим образом:

```text
--- build/ --- lib/
or
--- build/ --- lib.<plat>/
               temp.<plat>/
```

где `<plat>` раскрывается в краткое описание текущей ОС/аппаратной платформы и версии Python. Первая форма, только с каталогом `lib`, используется для «дистрибутивов чистых модулей» – то есть для дистрибутивов, содержащих только чистые модули Python. Если дистрибутив модуля содержит расширения (модули на C/C++), то используется вторая форма – с двумя каталогами `<plat>`. В этом случае каталог `temp.plat` содержит временные файлы, создаваемые в процессе компиляции/компоновки, которые фактически не устанавливаются. В любом случае каталог `lib` (или `lib.plat`) содержит все модули Python (чистые и расширения), которые будут установлены.

В будущем будут добавлены дополнительные каталоги для размещения скриптов Python, документации, исполняемых файлов и всего остального, что необходимо для установки модулей и приложений Python.

### Как работает установка

После выполнения команды **build** (явно или автоматически командой **install**) работа команды **install** становится относительно простой: ей остаётся только скопировать всё содержимое из `build/lib` (или `build/lib.plat`) в выбранный каталог установки.

Если не указать каталог установки (то есть просто запустить `setup.py install`), то команда **install** устанавливает модули в стандартный каталог для сторонних модулей Python. Этот каталог зависит от платформы и от того, как собран или установлен сам Python. На Unix (и Mac OS X, которая также основана на Unix) это также зависит от того, является ли устанавливаемый дистрибутив модуля чисто Python или содержит расширения («нечистый»):

| Платформа | Стандартное расположение установки | Значение по умолчанию | Примечания |
| --- | --- | --- | --- |
| Unix (чистый) | `prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |
| Unix (не чистый) | `exec-prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |
| Windows | `prefix\Lib\site-packages` | `C:\PythonXY\Lib\site-packages` | (2) |

Примечания:

1. Большинство дистрибутивов Linux включают Python как стандартную часть системы, поэтому `prefix` и `exec-prefix` обычно оба равны `/usr` в Linux. Если вы собираете Python самостоятельно в Linux (или любой Unix-подобной системе), то значения по умолчанию для `prefix` и `exec-prefix` – `/usr/local`.
2. Каталог установки по умолчанию в Windows был `C:\Program Files\Python` в Python 1.6a1, 1.5.2 и более ранних версиях.

`prefix` и `exec-prefix` обозначают каталоги, в которые установлен Python и где он ищет библиотеки во время выполнения. Под Windows они всегда одинаковы, а под Unix и Mac OS X – чаще всего одинаковы. Узнать, какие значения использует установка Python для `prefix` и `exec-prefix`, можно, запустив Python в интерактивном режиме и введя несколько простых команд. Под Unix просто введите `python` в командной строке. Под Windows выберите Пуск ‣ Программы ‣ Python X.Y ‣ Python (командная строка). После запуска интерпретатора введите код Python в приглашении. Например, в моей системе Linux я ввожу три оператора Python, показанные ниже, и получаю вывод, как показано, чтобы узнать мои `prefix` и `exec-prefix`:

```pycon
Python 2.4 (#26, Aug  7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'
```

В этом документе используются и другие заполнители: `X.Y` обозначает версию Python, например `3.2`; `abiflags` заменяется на значение [`sys.abiflags`](https://python-all.ru/3.7/library/sys.html#sys.abiflags) или пустую строку для платформ, не определяющих флаги ABI; `distname` заменяется на имя устанавливаемого дистрибутива модуля. Точки и регистр букв важны в путях; например, значение, использующее `python3.2` в UNIX, в Windows обычно имеет вид `Python32`.

Если вы не хотите устанавливать модули в стандартное расположение или у вас нет прав на запись туда, обратитесь к разделу [Альтернативная установка](https://python-all.ru/3.7/install/index.html#inst-alt-install). Если вы хотите более глубоко настроить каталоги установки, см. раздел [Пользовательская установка](https://python-all.ru/3.7/install/index.html#inst-custom-install).

## Альтернативная установка

Часто необходимо или желательно устанавливать модули в расположение, отличное от стандартного для сторонних модулей Python. Например, в системе Unix у вас может не быть прав на запись в стандартный каталог сторонних модулей. Или вы можете захотеть опробовать модуль, прежде чем делать его стандартной частью вашей локальной установки Python. Это особенно актуально при обновлении уже установленного дистрибутива: вы хотите убедиться, что существующая база скриптов продолжает работать с новой версией, прежде чем выполнять обновление.

Команда **install** из пакета Distutils предназначена для простой и безболезненной установки дистрибутивов модулей в альтернативное расположение. Основная идея: указывается базовый каталог для установки, а команда **install** выбирает набор каталогов (называемый *схемой установки*) внутри этого базового каталога, куда будут установлены файлы. Детали различаются в зависимости от платформы, поэтому следует прочитать соответствующий раздел.

Обратите внимание, что различные альтернативные схемы установки являются взаимоисключающими: можно указать `--user`, или `--home`, или `--prefix` и `--exec-prefix`, или `--install-base` и `--install-platbase`, но нельзя смешивать варианты из этих групп.

### Альтернативная установка: схема пользователя

Эта схема предназначена для наиболее удобного решения для пользователей, у которых нет прав на запись в глобальный каталог site-packages или которые не хотят в него устанавливать. Она включается простым параметром:

```text
python setup.py install --user
```

Файлы будут установлены в подкаталоги каталога [`site.USER_BASE`](https://python-all.ru/3.7/library/site.html#site.USER_BASE) (далее обозначается как `userbase`). Эта схема устанавливает чистые модули Python и модули расширений в одно и то же место (также известное как [`site.USER_SITE`](https://python-all.ru/3.7/library/site.html#site.USER_SITE)). Вот значения для UNIX, включая Mac OS X:

| Тип файла | Каталог установки |
| --- | --- |
| Модули | `userbase/lib/pythonX.Y/site-packages` |
| Скрипты | `userbase/bin` |
| Данные | `userbase` |
| Заголовочные файлы C | `userbase/include/pythonX.Yabiflags/distname` |

А вот значения, используемые в Windows:

| Тип файла | Каталог установки |
| --- | --- |
| Модули | `userbase\PythonXY\site-packages` |
| Скрипты | `userbase\PythonXY\Scripts` |
| Данные | `userbase` |
| Заголовочные файлы C | `userbase\PythonXY\Include{distname}` |

Преимущество использования этой схемы по сравнению с другими, описанными ниже, заключается в том, что каталог пользовательских site-packages в обычных условиях всегда включён в [`sys.path`](https://python-all.ru/3.7/library/sys.html#sys.path) (см. [`site`](https://python-all.ru/3.7/library/site.html#module-site) для получения дополнительной информации), а значит, после запуска скрипта `setup.py` для завершения установки не требуется выполнять никаких дополнительных действий.

Команда **build\_ext** также имеет параметр `--user` для добавления `userbase/include` в путь поиска компилятора для заголовочных файлов и `userbase/lib` в путь поиска компилятора для библиотек, а также в путь поиска времени выполнения для разделяемых C-библиотек (rpath).

### Альтернативная установка: схема home

Идея «домашней схемы» заключается в том, что вы создаёте и поддерживаете личную коллекцию модулей Python. Название этой схемы происходит от идеи «домашнего» каталога в Unix, поскольку пользователи Unix нередко делают свой домашний каталог похожим на `/usr/` или `/usr/local/`. Эту схему может использовать кто угодно, независимо от операционной системы, для которой выполняется установка.

Установка нового дистрибутива модуля так же проста, как

```text
python setup.py install --home=<dir>
```

где для параметра `--home` можно указать любой каталог. В Unix ленивые могут просто ввести тильду (`~`); команда **install** развернёт её в домашний каталог:

```text
python setup.py install --home=~
```

Чтобы Python находил дистрибутивы, установленные с помощью этой схемы, может потребоваться [изменить путь поиска Python](https://python-all.ru/3.7/install/index.html#inst-search-path) или отредактировать `sitecustomize` (см. [`site`](https://python-all.ru/3.7/library/site.html#module-site)) для вызова [`site.addsitedir()`](https://python-all.ru/3.7/library/site.html#site.addsitedir) или редактирования [`sys.path`](https://python-all.ru/3.7/library/sys.html#sys.path).

Параметр `--home` определяет базовый каталог установки. Файлы устанавливаются в следующие каталоги внутри базового каталога установки:

| Тип файла | Каталог установки |
| --- | --- |
| Модули | `home/lib/python` |
| Скрипты | `home/bin` |
| Данные | `home` |
| Заголовочные файлы C | `home/include/python/distname` |

(Мысленно замените косые черты на обратные, если вы работаете в Windows.)

### Альтернативная установка: Unix (схема prefix)

Префиксная схема полезна, если вы хотите использовать одну установку Python для сборки/установки (т.е. для запуска setup-скрипта), но устанавливать модули в каталог сторонних модулей другой установки Python (или того, что выглядит как другая установка Python). Если это звучит немного необычно – так и есть, поэтому сначала идут схемы пользователя и домашняя. Однако есть как минимум два известных случая, где префиксная схема окажется полезной.

Во-первых, учтите, что многие дистрибутивы Linux помещают Python в `/usr`, а не в более традиционный `/usr/local`. Это совершенно оправданно, поскольку в таких случаях Python является частью «системы», а не локальным дополнением. Однако если вы устанавливаете модули Python из исходных кодов, вы, вероятно, захотите поместить их в `/usr/local/lib/python2.X`, а не в `/usr/lib/python2.X`. Это можно сделать с помощью

```text
/usr/bin/python setup.py install --prefix=/usr/local
```

Другая возможность – сетевая файловая система, где имя, используемое для записи в удалённый каталог, отличается от имени, используемого для его чтения: например, интерпретатор Python, доступный как `/usr/local/bin/python`, может искать модули в `/usr/local/lib/python2.X`, но эти модули должны быть установлены, скажем, в `/mnt/@server/export/lib/python2.X`. Это можно было бы сделать с помощью

```text
/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
```

В любом случае параметр `--prefix` задаёт базовый каталог установки, а параметр `--exec-prefix` – базовый каталог для платформозависимой установки, который используется для файлов, зависящих от платформы. (Сейчас это относится только к неплатформенным дистрибутивам модулей, но может быть расширено на библиотеки C, исполняемые файлы и т.д.) Если `--exec-prefix` не указан, по умолчанию он равен `--prefix`. Файлы устанавливаются следующим образом:

| Тип файла | Каталог установки |
| --- | --- |
| Модули Python | `prefix/lib/pythonX.Y/site-packages` |
| Модули расширения | `exec-prefix/lib/pythonX.Y/site-packages` |
| Скрипты | `prefix/bin` |
| Данные | `prefix` |
| Заголовочные файлы C | `prefix/include/pythonX.Yabiflags/distname` |

Не требуется, чтобы `--prefix` или `--exec-prefix` обязательно указывали на другую установку Python. Если перечисленные выше каталоги ещё не существуют, они создаются во время установки.

Кстати, настоящая причина, по которой важна префиксная схема, просто в том, что стандартная установка Unix использует префиксную схему, но с `--prefix` и `--exec-prefix`, которые Python задаёт сам как `sys.prefix` и `sys.exec_prefix`. Поэтому может показаться, что префиксная схема никогда не понадобится, но каждый раз, когда вы запускаете `python setup.py install` без других параметров, вы её используете.

Обратите внимание, что установка расширений в другую установку Python не влияет на то, как эти расширения собираются: в частности, при компиляции расширений используются заголовочные файлы Python (`Python.h` и другие) из интерпретатора, который запускает сценарий установки. Именно вы отвечаете за то, чтобы интерпретатор, используемый для запуска установленных таким образом расширений, был совместим с тем, на котором они собирались. Лучший способ это сделать – убедиться, что оба интерпретатора относятся к одной версии Python (возможны разные сборки или просто копии одной и той же сборки). (Разумеется, если ваши `--prefix` и `--exec-prefix` вообще не указывают на другую установку Python, это не имеет значения.)

### Альтернативная установка: Windows (префиксная схема)

В Windows нет понятия домашнего каталога пользователя, и поскольку стандартная установка Python в Windows проще, чем в Unix, параметр `--prefix` традиционно используется для установки дополнительных пакетов в отдельные каталоги.

```text
python setup.py install --prefix="\Temp\Python"
```

для установки модулей в каталог `\Temp\Python` на текущем диске.

Базовый каталог установки задаётся параметром `--prefix`. Параметр `--exec-prefix` в Windows не поддерживается, поэтому чистые модули Python и модули расширения устанавливаются в одно и то же место. Файлы устанавливаются следующим образом:

| Тип файла | Каталог установки |
| --- | --- |
| Модули | `prefix\Lib\site-packages` |
| Скрипты | `prefix\Scripts` |
| Данные | `prefix` |
| Заголовочные файлы C | `prefix\Include{distname}` |

## Пользовательская установка

Иногда описанные в разделе [Alternate Installation](https://python-all.ru/3.7/install/index.html#inst-alt-install) схемы альтернативной установки не делают того, что нужно. Возможно, вы хотите подправить всего один-два каталога, оставив всё остальное в том же базовом каталоге, или полностью переопределить схему установки. В любом случае вы создаёте *пользовательскую схему установки*.

Чтобы создать пользовательскую схему установки, возьмите одну из альтернативных схем и переопределите некоторые каталоги установки для разных типов файлов с помощью следующих параметров:

| Тип файла | Переопределяющий параметр |
| --- | --- |
| Модули Python | `--install-purelib` |
| Модули расширения | `--install-platlib` |
| Все модули | `--install-lib` |
| Скрипты | `--install-scripts` |
| Данные | `--install-data` |
| Заголовочные файлы C | `--install-headers` |

Эти переопределяющие параметры могут быть относительными, абсолютными или явно заданными через один из базовых каталогов установки. (Базовых каталогов два, и обычно они совпадают – различие появляется только при использовании префиксной схемы Unix с разными значениями `--prefix` и `--exec-prefix`; использование `--install-lib` переопределяет значения, вычисленные или заданные для `--install-purelib` и `--install-platlib`, и рекомендуется для схем, где нет различий между модулями Python и расширениями.)

Например, вы устанавливаете дистрибутив модулей в свой домашний каталог в Unix, но хотите, чтобы скрипты помещались в `~/scripts`, а не в `~/bin`. Как и следовало ожидать, это можно сделать с помощью параметра `--install-scripts`. В данном случае разумнее всего указать относительный путь, который будет интерпретироваться относительно базового каталога установки (в данном случае – вашего домашнего каталога):

```text
python setup.py install --home=~ --install-scripts=scripts
```

Другой пример для Unix: допустим, установка Python была собрана и установлена с префиксом `/usr/local/python`, поэтому при стандартной установке скрипты окажутся в `/usr/local/python/bin`. Чтобы поместить их в `/usr/local/bin`, следует указать этот абсолютный путь для параметра `--install-scripts`:

```text
python setup.py install --install-scripts=/usr/local/bin
```

(Эта установка выполняется по «схеме префикса», где префикс – это тот, с которым был установлен интерпретатор Python, – в данном случае `/usr/local/python`.)

Если вы сопровождаете Python в Windows, возможно, требуется, чтобы сторонние модули располагались в подкаталоге `prefix`, а не прямо в самом `prefix`. Это почти так же просто, как настройка каталога установки скриптов – нужно лишь помнить, что существует два типа модулей: Python-модули и модули расширения, которыми удобно управлять с помощью одного параметра:

```text
python setup.py install --install-lib=Site
```

Указанный каталог установки указывается относительно `prefix`. Разумеется, также нужно убедиться, что этот каталог находится в пути поиска модулей Python, например, поместив файл `.pth` в site-каталог (см. [`site`](https://python-all.ru/3.7/library/site.html#module-site)). О том, как изменить путь поиска Python, рассказано в разделе [Изменение пути поиска Python](https://python-all.ru/3.7/install/index.html#inst-search-path).

Если требуется определить полную схему установки, нужно просто указать все параметры каталогов установки. Рекомендуется задавать относительные пути; например, если все файлы, связанные с модулями Python, должны находиться в каталоге `python` в вашем домашнем каталоге, и для каждой платформы, с которой этот домашний каталог используется, нужен отдельный каталог, можно определить следующую схему установки:

```text
python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data
```

или, что то же самое,

```text
python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data
```

`$PLAT` не (обязательно) является переменной окружения – он будет развёрнут Distutils при разборе параметров командной строки, так же как и при разборе файлов конфигурации.

Очевидно, указывать полную схему установки при каждой установке нового дистрибутива модуля было бы очень утомительно. Поэтому эти параметры можно поместить в файл конфигурации Distutils (см. раздел [Файлы конфигурации Distutils](https://python-all.ru/3.7/install/index.html#inst-config-files)):

```ini
[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data
```

или, что то же самое,

```ini
[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data
```

Обратите внимание, что эти два варианта *не* эквивалентны, если при запуске скрипта setup указать другой базовый каталог установки. Например,

```text
python setup.py install --install-base=/tmp
```

установит чистые модули в `/tmp/python/lib` в первом случае и в `/tmp/lib` во втором. (Для второго случая, вероятно, следует указать базовый каталог установки `/tmp/python`.)

Вероятно, вы заметили использование `$HOME` и `$PLAT` в примере входного файла конфигурации. Это переменные конфигурации Distutils, которые сильно напоминают переменные окружения. На самом деле, переменные окружения можно использовать в файлах конфигурации на платформах, где они есть, но Distutils дополнительно определяет несколько дополнительных переменных, которых может не быть в вашем окружении, например `$PLAT`. (И, конечно, в системах без переменных окружения, таких как Mac OS 9, переменные конфигурации, предоставляемые Distutils, являются единственными, которые можно использовать.) Подробнее см. раздел [Файлы конфигурации Distutils](https://python-all.ru/3.7/install/index.html#inst-config-files).

> **Примечание**
>
> Когда [виртуальное окружение](https://python-all.ru/3.7/library/venv.html#venv-def) активировано, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения.

### Изменение пути поиска Python

Когда интерпретатор Python выполняет инструкцию [`import`](https://python-all.ru/3.7/reference/simple_stmts.html#import), он ищет как код Python, так и модули расширения по пути поиска. Значение пути по умолчанию задаётся в двоичном файле Python при сборке интерпретатора. Узнать этот путь можно, импортировав модуль [`sys`](https://python-all.ru/3.7/library/sys.html#module-sys) и выведя значение `sys.path`.

```text
$ python
Python 2.2 (#11, Oct  3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
 '/usr/local/lib/python2.3/site-packages']
>>>
```

Пустая строка в `sys.path` обозначает текущий рабочий каталог.

Обычная практика для локально установленных пакетов – помещать их в каталог `…/site-packages/`, но может потребоваться установить Python-модули в произвольный каталог. Например, на вашем сайте может быть принято хранить всё программное обеспечение, связанное с веб-сервером, в каталоге `/www`. Тогда дополнительные модули Python могут находиться в `/www/python`, и чтобы импортировать их, этот каталог должен быть добавлен в `sys.path`. Есть несколько различных способов добавить каталог.

Самый удобный способ – добавить файл конфигурации пути в каталог, уже находящийся в пути поиска Python, обычно в каталог `.../site-packages/`. Файлы конфигурации пути имеют расширение `.pth`, и каждая строка должна содержать один путь, который будет добавлен в `sys.path`. (Поскольку новые пути добавляются в `sys.path`, модули в добавленных каталогах не переопределяют стандартные модули. Это означает, что этот механизм нельзя использовать для установки фиксированных версий стандартных модулей.)

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

Чуть менее удобный способ – отредактировать файл `site.py` в стандартной библиотеке Python и изменить `sys.path`. `site.py` автоматически импортируется при запуске интерпретатора Python, если не указан ключ [`-S`](https://python-all.ru/3.7/using/cmdline.html#id3), отключающий это поведение. Поэтому можно просто отредактировать `site.py` и добавить в него две строки:

```python
import sys
sys.path.append('/www/python/')
```

Однако если переустановить ту же самую мажорную версию Python (например, при обновлении с 2.2 до 2.2.2), `site.py` будет перезаписан стандартной версией. Перед выполнением установки придётся запомнить, что он был изменён, и сохранить копию.

Существуют две переменные окружения, которые могут изменить `sys.path`. [`PYTHONHOME`](https://python-all.ru/3.7/using/cmdline.html#envvar-PYTHONHOME) задаёт альтернативное значение префикса установки Python. Например, если [`PYTHONHOME`](https://python-all.ru/3.7/using/cmdline.html#envvar-PYTHONHOME) установлена в `/www/python`, путь поиска будет установлен в `['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]`.

Переменная [`PYTHONPATH`](https://python-all.ru/3.7/using/cmdline.html#envvar-PYTHONPATH) может быть установлена в список путей, которые будут добавлены в начало `sys.path`. Например, если [`PYTHONPATH`](https://python-all.ru/3.7/using/cmdline.html#envvar-PYTHONPATH) установлена в `/www/python:/opt/py`, путь поиска начнётся с `['/www/python', '/opt/py']`. (Обратите внимание: каталоги должны существовать, чтобы быть добавленными в `sys.path`; модуль [`site`](https://python-all.ru/3.7/library/site.html#module-site) удаляет несуществующие пути.)

Наконец, `sys.path` – это обычный список Python, поэтому любое приложение Python может изменять его, добавляя или удаляя записи.

## Файлы конфигурации Distutils

Как упоминалось выше, файлы конфигурации Distutils можно использовать для сохранения личных настроек или настроек сайта для любых параметров Distutils. То есть любой параметр любой команды может быть сохранён в одном из двух или трёх (в зависимости от платформы) файлов конфигурации, которые будут обрабатываться до разбора командной строки. Это означает, что файлы конфигурации переопределяют значения по умолчанию, а командная строка, в свою очередь, переопределяет файлы конфигурации. Кроме того, если применяется несколько файлов конфигурации, значения из «более ранних» файлов переопределяются «более поздними».

### Расположение и имена файлов конфигурации

Имена и расположение конфигурационных файлов немного различаются в зависимости от платформы. На Unix и Mac OS X три конфигурационных файла (в порядке их обработки):

| Тип файла | Расположение и имя файла | Примечания |
| --- | --- | --- |
| системный | `prefix/lib/pythonver/distutils/distutils.cfg` | (1) |
| личный | `$HOME/.pydistutils.cfg` | (2) |
| локальный | `setup.cfg` | (3) |

А в Windows файлы конфигурации:

| Тип файла | Расположение и имя файла | Примечания |
| --- | --- | --- |
| системный | `prefix\Lib\distutils\distutils.cfg` | (4) |
| личный | `%HOME%\pydistutils.cfg` | (5) |
| локальный | `setup.cfg` | (3) |

На всех платформах «личный» файл можно временно отключить, передав параметр *–no-user-cfg*.

Примечания:

1. Строго говоря, общесистемный файл конфигурации находится в каталоге, где установлен Distutils; в Python 1.6 и новее в Unix это так, как показано. В Python 1.5.2 Distutils обычно устанавливается в `prefix/lib/python1.5/site-packages/distutils`, поэтому при использовании Python 1.5.2 системный файл конфигурации следует размещать там.
2. В Unix, если переменная окружения `HOME` не определена, домашний каталог пользователя определяется с помощью функции `getpwuid()` из стандартного модуля [`pwd`](https://python-all.ru/3.7/library/pwd.html#module-pwd). Это делает функция [`os.path.expanduser()`](https://python-all.ru/3.7/library/os.path.html#os.path.expanduser), используемая в Distutils.
3. То есть в текущем каталоге (обычно там, где находится сценарий setup).
4. (См. также примечание (1).) В Python 1.6 и новее префикс установки Python по умолчанию – `C:\Python`, поэтому системный файл конфигурации обычно находится в `C:\Python\Lib\distutils\distutils.cfg`. В Python 1.5.2 префикс по умолчанию был `C:\Program Files\Python`, а Distutils не входили в стандартную библиотеку, поэтому системный файл конфигурации находился бы в `C:\Program Files\Python\distutils\distutils.cfg` в стандартной установке Python 1.5.2 в Windows.
5. В Windows, если переменная окружения `HOME` не определена, то перебираются `USERPROFILE`, `HOMEDRIVE` и `HOMEPATH`. Это делается функцией [`os.path.expanduser()`](https://python-all.ru/3.7/library/os.path.html#os.path.expanduser), используемой в Distutils.

### Синтаксис файлов конфигурации

Все файлы конфигурации Distutils имеют одинаковый синтаксис. Файлы конфигурации разбиты на разделы. Для каждой команды Distutils есть отдельный раздел, плюс раздел `global` для глобальных параметров, влияющих на все команды. Каждый раздел содержит по одному параметру на строку, задаваемому в формате `option=value`.

Например, ниже приведён полный файл конфигурации, который заставляет все команды по умолчанию работать в тихом режиме:

```ini
[global]
verbose=0
```

Если этот файл установлен как системный конфигурационный, он влияет на обработку любых дистрибутивов модулей Python любым пользователем в данной системе. Если установлен как ваш личный конфигурационный файл (в системах, которые это поддерживают), он влияет только на дистрибутивы модулей, обрабатываемые вами. А если используется как `setup.cfg` для конкретного дистрибутива модуля, то влияет только на этот дистрибутив.

Можно переопределить каталог «build base» по умолчанию и заставить команды **build\*** всегда принудительно пересобирать все файлы следующим образом:

```ini
[build]
build-base=blib
force=1
```

что соответствует аргументам командной строки

```text
python setup.py build --build-base=blib --force
```

за исключением того, что указание команды **build** в командной строке означает, что эта команда будет выполнена. Включение конкретной команды в файлы конфигурации не имеет такого смысла; это лишь означает, что если команда будет выполнена, то будут применены параметры из файла конфигурации. (Или если будут выполнены другие команды, которые используют её значения, они возьмут значения из файла конфигурации.)

Полный список параметров для любой команды можно узнать с помощью опции `--help`, например:

```text
python setup.py build --help
```

а полный список глобальных параметров – с помощью `--help` без указания команды:

```text
python setup.py --help
```

См. также раздел «Справочник» в руководстве «Распространение модулей Python».

## Сборка расширений: советы и хитрости

По возможности Distutils стараются использовать информацию о конфигурации, предоставляемую интерпретатором Python, который запускает сценарий `setup.py`. Например, те же флаги компилятора и компоновщика, которые использовались для сборки Python, будут использоваться и для компиляции расширений. Обычно это работает хорошо, но в сложных ситуациях может быть неприемлемо. В этом разделе рассматривается, как переопределить стандартное поведение Distutils.

### Настройка флагов компилятора/компоновщика

Компиляция расширения Python, написанного на C или C++, иногда требует указания пользовательских флагов для компилятора и компоновщика, чтобы использовать конкретную библиотеку или создать особый вид объектного кода. Особенно это актуально, если расширение не тестировалось на вашей платформе или вы пытаетесь кросс-компилировать Python.

В самом общем случае автор расширения мог предвидеть, что компиляция расширений будет сложной, и предоставил файл `Setup` для редактирования. Скорее всего, это делается только тогда, когда дистрибутив модуля содержит много отдельных модулей расширения или они часто требуют сложных наборов флагов компилятора для работы.

Файл `Setup`, если присутствует, разбирается для получения списка расширений для сборки. Каждая строка в `Setup` описывает один модуль. Строки имеют следующую структуру:

```text
module ... [sourcefile ...] [cpparg ...] [library ...]
```

Рассмотрим каждое поле по порядку.

- *module* – это имя собираемого модуля расширения, и оно должно быть корректным идентификатором Python. Просто изменить его, чтобы переименовать модуль, нельзя (потребуется также править исходный код), поэтому его следует оставить как есть.
- *sourcefile* – это любой файл, который, по крайней мере судя по имени, может быть исходным кодом. Файлы с расширением `.c` считаются написанными на C, файлы с расширениями `.C`, `.cc` и `.c++` – на C++, а файлы с расширениями `.m` или `.mm` – на Objective C.
- *cpparg* – это аргумент для препроцессора C, и им может быть всё, что начинается с `-I`, `-D`, `-U` или `-C`.
- *library* – это всё, что заканчивается на `.a` или начинается с `-l` или `-L`.

Если для вашей платформы требуется особая библиотека, её можно добавить, отредактировав файл `Setup` и запустив `python setup.py build`. Например, если модуль, заданный строкой

```text
foo foomodule.c
```

должен быть слинкован с математической библиотекой `libm.a` на вашей платформе, просто добавьте `-lm` в строку:

```text
foo foomodule.c -lm
```

Произвольные опции для компилятора или компоновщика можно передать с помощью опций `-Xcompiler` *аргумент* и `-Xlinker` *аргумент*:

```text
foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
```

Следующая после `-Xcompiler` и `-Xlinker` опция будет добавлена в соответствующую командную строку, поэтому в приведённом примере компилятор получит опцию `-o32`, а компоновщик – `-shared`. Если опция компилятора требует аргумента, придётся указать несколько опций `-Xcompiler`; например, чтобы передать `-x c++`, файл `Setup` должен содержать `-Xcompiler -x -Xcompiler c++`.

Флаги компилятора можно также задать через переменную окружения `CFLAGS`. Если она установлена, содержимое `CFLAGS` будет добавлено к флагам компилятора, указанным в файле `Setup`.

### Использование компиляторов не от Microsoft в Windows

#### Borland/CodeGear C++

В этом подразделе описаны необходимые шаги для использования Distutils с компилятором Borland C++ версии 5.5. Прежде всего, необходимо знать, что формат объектных файлов Borland (OMF) отличается от формата, используемого в версии Python, которую можно загрузить с веб-сайтов Python или ActiveState. (Python собирается с помощью Microsoft Visual C++, который использует COFF в качестве формата объектных файлов.) По этой причине необходимо преобразовать библиотеку Python `python25.lib` в формат Borland. Это можно сделать следующим образом:

```text
coff2omf python25.lib python25_bcpp.lib
```

Программа `coff2omf` поставляется с компилятором Borland. Файл `python25.lib` находится в каталоге `Libs` вашей установки Python. Если ваше расширение использует другие библиотеки (zlib, …), их тоже нужно преобразовать.

Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.

Как Distutils умудряется использовать эти библиотеки с изменёнными именами? Если расширению нужна библиотека (например, `foo`), Distutils сначала проверяет, найдётся ли библиотека с суффиксом `_bcpp` (например, `foo_bcpp.lib`), и использует её. Если такой специальной библиотеки нет, используется имя по умолчанию (`foo.lib`). [1](https://python-all.ru/3.7/install/index.html#id4)

Чтобы Distutils собрал ваше расширение с Borland C++, введите:

```text
python setup.py build --compiler=bcpp
```

Если вы хотите использовать компилятор Borland C++ по умолчанию, это можно указать в вашем личном или общесистемном конфигурационном файле Distutils (см. раздел [Distutils Configuration Files](https://python-all.ru/3.7/install/index.html#inst-config-files)).

> **См. также**
>
> **[Компилятор C++Builder](https://python-all.ru/3.7/install/index.html)**
>
> Информация о бесплатном компиляторе C++ от Borland, включая ссылки на страницы загрузки.
>
> **[Создание расширений Python с помощью бесплатного компилятора Borland](https://python-all.ru/3.7/install/index.html)**
>
> Документ, описывающий, как использовать бесплатный компилятор C++ командной строки Borland для сборки Python.

#### GNU C / Cygwin / MinGW

В этом разделе описаны необходимые шаги для использования Distutils с компиляторами GNU C/C++ в дистрибутивах Cygwin и MinGW. [2](https://python-all.ru/3.7/install/index.html#id5) Для интерпретатора Python, собранного с помощью Cygwin, всё должно работать без каких-либо дополнительных действий.

Не все расширения можно собрать с MinGW или Cygwin, но многие можно. Вероятнее всего, не будут работать расширения, использующие C++ или зависящие от расширений Microsoft Visual C.

Чтобы Distutils собрал ваше расширение с Cygwin, введите:

```text
python setup.py build --compiler=cygwin
```

а для Cygwin в режиме no-cygwin [3](https://python-all.ru/3.7/install/index.html#id6) или для MinGW введите:

```text
python setup.py build --compiler=mingw32
```

Если вы хотите использовать любую из этих опций/компиляторов по умолчанию, стоит записать это в ваш личный или общесистемный конфигурационный файл Distutils (см. раздел [Distutils Configuration Files](https://python-all.ru/3.7/install/index.html#inst-config-files)).

##### Старые версии Python и MinGW

Следующие инструкции применимы только в том случае, если вы используете версию Python ниже 2.4.1 с MinGW ниже 3.0.0 (с binutils-2.13.90-20030111-1).

Эти компиляторы требуют некоторых специальных библиотек. Эта задача сложнее, чем для Borland C++, потому что нет программы для преобразования библиотеки. Сначала нужно создать список символов, которые экспортирует DLL Python. (Хорошую программу для этой задачи можно найти на [https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/](https://python-all.ru/3.7/install/index.html)).

```text
pexports python25.dll >python25.def
```

Расположение установленного `python25.dll` зависит от параметров установки, версии и языка Windows. При установке «только для меня» он будет находиться в корневом каталоге установки. При общей установке – в системном каталоге.

Затем на основе этой информации можно создать импортную библиотеку для gcc.

```text
/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
```

Полученную библиотеку нужно поместить в тот же каталог, что и `python25.lib`. (Обычно это каталог `libs` в каталоге установки Python.)

Если ваше расширение использует другие библиотеки (zlib,…), их, возможно, тоже придётся преобразовать. Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.

> **См. также**
>
> **[Сборка модулей Python на платформе MS Windows с помощью MinGW](https://python-all.ru/3.7/install/index.html)**
>
> Информация о сборке необходимых библиотек для окружения MinGW.

Сноски

**[1](https://python-all.ru/3.7/install/index.html#id1)**

Это также означает, что можно заменить все существующие COFF-библиотеки на OMF-библиотеки с теми же именами.

**[2](https://python-all.ru/3.7/install/index.html#id2)**

Проверьте [https://www.sourceware.org/cygwin/](https://python-all.ru/3.7/install/index.html) и [http://www.mingw.org/](https://python-all.ru/3.7/install/index.html) для получения дополнительной информации

**[3](https://python-all.ru/3.7/install/index.html#id3)**

В этом случае эмуляция POSIX недоступна, но и необходимость в `cygwin1.dll` отпадает.