# Python モジュールのインストール (旧版)

著者

  Greg Ward --- 日本語訳: Python ドキュメント翻訳プロジェクト

注釈

`distutils` パッケージ全体の使用は非推奨 (deprecated) であり、Python 3.12 で削除されます。この文書は参照のために維持されており、パッケージとともに削除されます。詳しくは What's New エントリを参照してください。

参考

Python モジュールのインストール

  Python モジュールのインストールに関するドキュメントの最新版です。通常の Python の利用の場合、このページよりも、ほぼ確実にこちらのドキュメントを参照したほうがよいでしょう。

注釈

このドキュメントは、 https://setuptools.readthedocs.io/en/latest/setuptools.html にある `setuptools` のドキュメントが現時点でここにある関連情報を全て網羅するまで、単独でここに載せておかれます。

注釈

このガイドは、Python のバージョンの一部として提供される拡張のビルドと配布についての基礎的なツールについてのみをカバーします。サードパーティによるツールが、容易に使えてもっと安全な代替として使えるでしょう。もっと詳しい情報は quick recommendations section にある Python パッケージングユーザガイドから得られます。

## はじめに

Python 2.0 において、 `distutils` API は初めて標準ライブラリに追加されました。このモジュールは、Linux ディストリビューションのメンテナンス担当者には Python プロジェクトを Linux ディストリビューションに変換する標準的な方法を提供しました。また、システム管理者には Python プロジェクトを対象のシステムにインストールする標準的な方法を提供しました。

Python 2.0 がリリースされてから何年もたち、ビルドシステムとパッケージのインストーラーを Python ランタイムのリリースサイクルと強く結合させることには問題があることがわかってきました。そして現在、プロジェクトは `distutils` を直接使うよりも `pip` パッケージインストーラーと `setuptools` ビルドシステムを使うことが推奨されています。

詳しくは Python モジュールのインストール と Python モジュールの配布 を参照してください。

このレガシードキュメントは、 `setuptools` のドキュメントが必要な全ての情報を網羅していると自信を持って言えるようになるまで保持されます。

### Distutils にもとづくソースコードの配布

モジュールのソースコード配布物をダウンロードしたら、配布物が標準のやり方、すなわち Distutils のやり方に従ってパッケージされて 配布されているかどうかすぐに分かります。Distutils の場合、まず配布物の名前とバージョン番号が、例えば `foo-1.0.tar.gz` や `widget-0.9.7.zip` のように、ダウンロードされたアーカイブファイルの 名前にはっきりと反映されます。次に、アーカイブは同様の名前のディレクトリ、例えば `foo-1.0` や `widget-0.9.7` に展開されます。さらに、配布物には setup スクリプト `setup.py` が入っています。また、 `README.txt` 場合によっては `README` という名前のファイルも入っていて、そこには、モジュール配布物の構築とインストールは簡単で、このようにするだけだ、とするだけだ、という説明が書かれているはずです

    python setup.py install

Windows ではこのコマンドは、コマンドプロンプトのウィンドウを開いて (スタート ‣ アクセサリ)、このように実行するのに違いありません

    setup.py install

上記の全てが当てはまるなら、ダウンロードしたものをビルドしてインストールする方法はすでに知っていることになります: 上記のコマンドを実行するだけです。非標準の方法でインストールを行ったり、ビルドプロセスをカスタマイズ行いたいのでない限り、このマニュアルは必要ありません。別の言葉で言えば、上のコマンドこそが、このマニュアルから習得すべき全てということになります。

## 標準的なビルド・インストール作業

Distutils にもとづくソースコードの配布 節で述べたように、 Distutils を使ったモジュール配布物のビルドとインストールは、通常は端末からの単純な以下コマンドで行います:

    python setup.py install

### プラットフォームによる違い

setup コマンドは常に配布物ルートディレクトリ、すなわちモジュールのソース配布物を展開した際のトップレベルのサブディレクトリ内で実行しなければなりません。例えば、あるモジュールのソース配布物 `foo-1.0.tar.gz` を Unix システム上にダウンロードしたなら、通常は以下の操作を行います:

    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` にダウンロードしたのなら、(WinZip のような) グラフィカルユーザインターフェースつきのアーカイブ操作ソフトや、 (unzip や pkunzip のような) コマンドラインツールを使ってアーカイブを `C:\Temp\foo-1.0` に展開します。次に、コマンドプロンプトウィンドウを開いて、以下を実行します:

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

### ビルド作業とインストール作業を分割する

`setup.py install` を実行すると、一度の実行で全てのモジュールをビルドしてインストールします。段階的に作業をしたい場合 --- ビルドプロセスをカスタマイズしたり、作業がうまくいかない場合に特に便利です --- には、setup スクリプトに一度に一つづつ作業を行わせるようにできます。この機能は、ビルドとインストールを異なるユーザで行う場合にも便利です --- 例えば、モジュール配布物をビルドしておいてシステム管理者に渡して (または、自分でスーパユーザになって)、インストールしたくなるかもしれません.

最初のステップでは全てをビルドしておき、次のステップで全てをインストールするには、setup スクリプトを二度起動します:

    python setup.py build
    python setup.py install

この作業を行ってみれば、 install コマンドを実行するとまず build コマンドを実行し、さらに --- この場合には --- `build` ディレクトリの中が全て最新の状態になっているので、 build は何も行わなくてよいと判断していることがわかるでしょう。

インターネットからダウンロードしたモジュールをインストールしたいだけなら、上のように作業を分割する機能は必要ないかもしれませんが、この機能はより進んだ使い方をする際にはとても便利です。自作の Python モジュールや拡張モジュールを配布することになれば、個々の Distutils コマンドを自分で何度も実行することになるでしょう。

### ビルドの仕組み

上で示唆したように、 build コマンドは、インストールすべきファイルを ビルドディレクトリ に置く働きがあります。デフォルトでは、ビルドディレクトリは配布物ルート下の `build` になります; システムの処理速度に強いこだわりがあったり、ソースツリーに指一本触れたくないのなら、 `--build-base` オプションを使ってビルドディレクトリを変更できます。例えば:

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

(あるいは、システム全体向け、あるいは個人用の Distutils 設定ファイルにディレクティブを書いて、永続的に設定を変えられます; Distutils 設定ファイル 節を参照してください。) 通常は必要ない作業です。

ビルドツリーのデフォルトのレイアウトは以下のようになっています:

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

`<plat>` は、現在の OS/ハードウェアプラットフォームと Python のバージョンを記述する短い文字列に展開されます。第一の `lib` ディレクトリだけの形式は、 "pure モジュール配布物" --- すなわち、pure Python モジュールだけの入ったモジュール配布物 --- の場合に使われます。モジュール配布物に何らかの拡張モジュール (C/C++ で書かれたモジュール) が入っている場合、第二の `<plat>` 付きディレクトリが二つある形式が使われます。この場合、 `temp.plat` ディレクトリには、コンパイル/リンク過程で生成され、実際にはインストールされない一時ファイルが収められます。どちらの場合にも、 `lib` (または `lib.plat`) ディレクトリには、最終的にインストールされることになる全ての Python モジュール (pure Python モジュールおよび拡張モジュール) が入ります。

今後、Python スクリプト、ドキュメント、バイナリ実行可能形式、その他 Python モジュールやアプリケーションのインストール作業に必要なディレクトリが追加されるかもしれません。

### インストールの仕組み

build コマンドを実行した後 (明示的に実行した場合も、 install コマンドが代わりに実行してくれた場合も) は、 install コマンドの仕事は比較的単純なもの: `build/lib` (または `build/lib.plat`) の下にあるもの全ての指定したインストールディレクトリへのコピー、になります。

インストールディレクトリを選ばなかった場合 --- すなわち、 `setup.py install` を実行しただけの場合 --- には、 install コマンドはサードパーティ製 Python モジュールを置くための標準の場所にインストールを行います。この場所は、プラットフォームや、Python 自体をどのようにビルド/インストールしたかで変わります。 Unix (と、Unix をベースとしたmacOS) では、インストールしようとするモジュール配布物が pure Python なのか、拡張モジュールを含む ("非 pure") のかによっても異なります:

プラットフォーム | 標準のインストール場所 | デフォルト値 | 注釈
--- | --- | --- | ---
Unix (pure) | `prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1)
Unix (非 pure) | `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 が入っているので、 Linux では普通、 `prefix` や `exec-prefix` はどちらも `/usr` になります。 Linux (または Unixライクなシステム) 上で自分で Python をビルドした場合、デフォルトの `prefix` および `exec-prefix` は `/usr/local` になります。

2. Windows での Python のデフォルトインストールディレクトリは、 Python 1.6a1、 1.5.2、およびそれ以前のバージョンでは `C:\Program Files\Python` です。

`prefix` および `exec-prefix` は、 Python がインストールされているディレクトリと、実行時にライブラリを探しにいく場所を表します。これらのディレクトリは、Windows では常に同じで、 Unixと macOS でもほぼ常に同じです。自分の Python がどんな `prefix` や `exec-prefix` を使っているかは、Python を対話モードで起動して、単純なコマンドをいくつか入力すればわかります。 Windows では、 スタート ‣ (すべての) プログラム ‣ Python X.Y ‣ Python (command line) を選びます。Unix では、シェルプロンプトで単に `python` と入力します。インタプリタを起動すると、プロンプトに Python コードを入力できます。例えば、著者の使っている Linux システムで、三つの Python 文を以下のように入力すると、出力から著者のシステムの `prefix` と `exec-prefix` を得られます:

    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` の値に置き換えられるか、プラットフォームが ABI フラグを定義しない場合、空文字列に置き換えられます; `distname` はインストールしようとしているモジュール配布物の名前に置き換えられます。ドットとキャピタライズはパス内で重要です; 例えば UNIX では `python3.2` が使われる値が、Windows では普通 `Python32` を使います。

モジュールを標準の場所にインストールしたくない場合や、標準の場所にインストールするためのファイル権限を持っていない場合、 別の場所へのインストール 節にある、別の場所へのインストール方法の説明を読んでください。インストール先のディレクトリを大幅にカスタマイズしければ、 カスタムのインストール 節のカスタムインストールに関する説明を読んでください。

## 別の場所へのインストール

しばしば、サードパーティ製 Python モジュールをインストールするための標準の場所以外にモジュールをインストールしなければならなかったり、単にそうしたくなるときがあります。例えばUnix システムでは、標準のサードパーティ製モジュールディレクトリに対する書き込み権限を持っていないかもしれません。または、あるモジュールを、ローカルで使っている Python に標準のモジュールの一部として組み込む前にテストしてみたいと思うかもしれません。既存の配布物をアップグレードする際には特にそうでしょう: 実際にアップグレードする前に、既存のスクリプトの基本となる部分が新たなバージョンでも動作するか確認したいはずです。

Distutils の install コマンドは、別の場所へ配布物をインストールする作業を単純で苦労のない作業にするように設計されています。基本的なアイデアは、インストール先のベースディレクトリを指定しておき、 install コマンドがそのベースディレクトリ下にファイル群をインストールするための一連のディレクトリ (インストールスキーム : installation scheme) を作成するというものです。詳細はプラットフォームによって異なるので、以下の節から自分のプラットフォームに当てはまるものを読んでください。

色々な代替インストールスキームは相互に排他的であることに注意してください: `--user`, または `--home`, または `--prefix` と `--exec-prefix`, または `--install-base` と `--install-platbase` を指定できますが、それらグループを混ぜこぜには使えません。

### 別の場所へのインストール: user スキーム

このスキームはグローバルな site-packages ディレクトリへの書き込み権限を持たないユーザあるいはそこにインストールしたくないユーザに最も便利な解法となるようデザインされています。簡単なオプションでこれが可能です:

    python setup.py install --user

ファイルは `site.USER_BASE` (以降 `userbase` と書きます) のサブディレクトリにインストールされます。このスキームでは pure Python モジュールと拡張モジュールは(`site.USER_SITE` としても知られる)同じ場所にインストールされます。macOS を含む UNIX の場合は下表の通りです:

ファイルのタイプ | インストールディレクトリ
--- | ---
モジュール | `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` に含まれる普通の状態にある(詳細は `site` 参照)ということで、つまり `setup.py` スクリプト後にインストールを完成させるための特別なステップが不要ということです。

さらに、コンパイラがヘッダファイルを検索するための `userbase/include` 、ライブラリを検索するための `userbase/lib` 、ランタイムの共有ライブラリを探すためのパス(rpath)を追加するために、 build_ext コマンドには `--user` オプションがあります。

### 別の場所へのインストール: home スキーム

"home スキーム" の背後にある考え方は、Python モジュールを個人用のモジュール置き場でビルドし、維持するというものです。このスキームの名前は Unixの「ホーム」ディレクトリの概念からとりました。というのも、 Unixのユーザにとって、自分のホームディレクトリを `/usr/` や `/usr/local/` のようにレイアウトするのはよくあることだからです。とはいえ、このスキームはどのオペレーティングシステムのユーザでも使えます。

新たなモジュールのインストールは単純で

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

のようにします。このとき、 `--home` オプションを使ってディレクトリを指定します。 Unix では、面倒臭がりの人は単にチルダ (`~`) をタイプするだけでかまいません; install コマンドがチルダをホームディレクトリに展開してくれます:

    python setup.py install --home=~

このスキームでインストールされた配布物を Python が見つけられるようにするために、 Python サーチパスの変更 をするか、 `sitecustomize` (`site` 参照) を編集して `site.addsitedir()` を呼び出すか、 `sys.path` を編集するかしないといけないかもしれません。

`--home` オプションは、インストールのベースディレクトリを指定します。 ファイルはインストールベース下の以下のディレクトリに保存されます:

ファイルのタイプ | インストールディレクトリ
--- | ---
モジュール | `home/lib/python`
スクリプト | `home/bin`
データ | `home`
C ヘッダー | `home/include/python/distname`

(Windows の場合はスラッシュをバックスラッシュに脳内変換)

### 別の場所へのインストール: Unix (prefix スキーム)

あるインストール済みの Python を使ってモジュールのビルド/インストールを (例えば setup スクリプトを実行して) 行いたいけれども、 別のインストール済みの Python のサードパーティ製モジュール置き場 (あるいは、そう見えるようなディレクトリ構造) に、ビルドされた モジュールをインストールしたい場合には、"prefix スキーム" が便利です。そんな作業はまったくありえそうにない、と思うなら、確かにその通りです --- "home スキーム" を先に説明したのもそのためです。とはいえ、prefix スキームが有用なケースは少なくとも二つあります。

まず、多くの Linux ディストリビューションは、 Python を `/usr/local` ではなく `/usr` に置いていることを考えてください。この場合は、 Python はローカルの計算機ごとのアドオン (add-on) ではなく、"システム" の一部となっているので、 `/usr` に置くのは全く正当なことです。しかしながら、 Python モジュールをソースコードからインストールしていると、モジュールを `/usr/lib/python2.X` ではなく `/usr/local/lib/python2.X` に置きたいと思うかもしれません。これを行うには、以下のように指定します

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

もう一つありえるのは、ネットワークファイルシステムにおいて、遠隔のディレクトリに対する読み出しと書き込みの際に違う名前を使う場合です。例えば、 `/usr/local/bin/python` でアクセスするような Python インタプリタは、 `/usr/local/lib/python2.X` からモジュールを探すでしょうが、モジュールは別の場所、例えば `/mnt/@server/export/lib/python2.X` にインストールしなければならないかもしれません。この場合には、以下のようにします

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

どちらの場合も、 `--prefix` オプションでインストール先のベースディレクトリが決まり、 `--exec-prefix` でプラットフォーム固有のファイルのための、プラットフォーム固有となるインストール先のベースディレクトリが決まります。 (プラットフォーム固有のファイルとは、現状では単に非 pure モジュール配布物のことを意味しますが、 C ライブラリやバイナリ実行可能形式などに拡張されるかもしれません。) `--exec-prefix` が指定されていなければ、デフォルトの `--prefix` になります。 ファイルは以下のようにインストールされます:

ファイルのタイプ | インストールディレクトリ
--- | ---
pure 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 の場所を指している必要はありません; 上に挙げたディレクトリがまだ存在しなければ、インストール時に作成されます。

ちなみに、prefix スキームが重要な本当の理由は、単に標準の Unix インストールが prefix スキームを使っているからです。 ただし、そのときには、 `--prefix` や `--exec-prefix` は Python 自体が `sys.prefix` や `sys.exec_prefix` を使って決めます。 というわけで、読者は prefix スキームを決して使うことはあるまいと思っているかもしれませんが、 `python setup.py install` をオプションを何もつけずに実行していれば、常に prefix スキームを使っていることになるのです。

拡張モジュールを別のインストール済み Python にインストールしても、拡張モジュールのビルド方法による影響を受けることはありません: 特に、拡張モジュールをコンパイルする際には、 setup スクリプトを実行する際に使う Python インタプリタと一緒にインストールされている Python ヘッダファイル (`Python.h` とその仲間たち) を使います。上で述べてきたやり方でインストールされた拡張モジュールを実行するインタプリタと、インタプリタをビルドする際に用いた別のインタプリタとの互換性を保証するのはユーザの責任です。これを行うには、二つのインタプリタが同じバージョンの Python (ビルドが違っていたり、同じビルドのコピーということもあり得ます) であるかどうかを確かめます。(もちろん、 `--prefix` や `--exec-prefix` が別のインストール済み Python の場所すら指していなければどうにもなりません。)

### 別の場所へのインストール (prefix を使う方法): Windows

Windows はユーザのホームディレクトリという概念がなく、 Windows 環境下で標準的にインストールされた Python は Unixよりも単純な構成をしているので、 Windows で追加のパッケージを別の場所に入れる場合には、伝統的に `--prefix` が使われてきました。

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

とすると、モジュールを現在のドライブの `\Temp\Python` ディレクトリにインストールします。

インストールベースディレクトリは、 `--prefix` オプションだけで決まります; `--exec-prefix` オプションは、Windows ではサポートされていません。pure モジュールと拡張モジュールは同じ場所にインストールされます。ファイルは以下のような構成でインストールされます:

ファイルのタイプ | インストールディレクトリ
--- | ---
モジュール | `prefix\Lib\site-packages`
スクリプト | `prefix\Scripts`
データ | `prefix`
C ヘッダー | `prefix\Include{distname}`

## カスタムのインストール

たまに、 別の場所へのインストール 節で述べたような別の場所へのインストールスキームが、自分のやりたいインストール方法と違うことがあります。もしかすると、同じベースディレクトリ下にあるディレクトリのうち、一つか二つだけをいじりたかったり、インストールスキームを完全に再定義したいと思うかもしれません。どちらの場合にせよ、こうした操作では カスタムのインストールスキーム を作成することになります。

カスタムインストールのためには、スキームの中のひとつから始めて、ファイルのタイプごとに使われるインストールディレクトリを以下オプションで上書きします:

ファイルのタイプ | 上書きオプション
--- | ---
pure Python モジュール | `--install-purelib`
拡張モジュール | `--install-platlib`
全てのモジュール | `--install-lib`
スクリプト | `--install-scripts`
データ | `--install-data`
C ヘッダー | `--install-headers`

これらの上書きオプションには相対パス、絶対パス、あるいはベースディレクトリのひとつとして明確に定義されたものを指定することができます（2つのベースディレクトリがあり、通常それらは同一です。これらは Unix の prefix スキームを選択し、 `--prefix` と `--exec-prefix` オプションに異なるパスを指定した場合にだけ同一でなくなります。 `--install-lib` を指定すると内部で設定された、あるいは指定された `--install-purelib` と `--install-platlib` を上書きしますので、この方法が pure モジュールと拡張モジュールのインストール先を同一とするようなスキームでは推奨されます）。

例えば、 Unix環境でモジュール配布物をホームディレクトリにインストールしたい --- とはいえ、スクリプトは `~/bin` ではなく `~/scripts` に置きたい --- とします。ご想像の通り、スクリプトを置くディレクトリは、 `--install-scripts` オプションで上書きできます; この場合は相対パスで指定もでき、インストールベースディレクトリ (この場合にはホームディレクトリ) からの相対パスとして解釈されます:

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

Unix 環境での例をもう一つ紹介します: インストール済みの Python が、 `/usr/local/python` を prefix にしてビルドされ、インストールされていて、標準のインストールスクリプトは `/usr/local/python/bin` に入るようになっているとします。 `/usr/local/bin` に入るようにしたければ、絶対パスを `--install-scripts` オプションに与えて上書きすることになるでしょう:

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

(この例は prefix スキームによるインストールを実行します。ここで prefix は Python インタープリタがインストールされている場所 --- この例では `/usr/local/python` --- になります。)

Windows 上の Python を管理している場合、サードパーティ製のモジュールは `prefix` 直下ではなく、 `prefix` 配下のサブディレクトリにインストールしたいと考えるかもしれません。これはスクリプトのインストール先ディレクトリをカスタマイズするのとほとんど同じくらいに簡単です。 --- 覚えておかなければならないのは、Python には pure モジュールと拡張モジュールの2種類があり、これらのインストール先はただひとつのオプションで簡単にコントロールできる、ということだけです。

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

指定したインストール先ディレクトリは、 `prefix` からの相対です。もちろん、 このディレクトリを `.pth` ファイルに入れるなどして(`site` 参照)、Python のモジュール検索パス内に入るようにしなければなりません。Python のモジュール検索パスを修正する方法は、 Python サーチパスの変更 節を参照してください。

インストールスキーム全体を定義したいのなら、全てのインストールディレクトリオプションを指定しなければなりません。この作業には、相対パスを使った指定を勧めます; 例えば、全ての Python モジュール関連ファイルをホームディレクトリ下の `python` ディレクトリの下に置き、そのホームディレクトリをマウントしている各プラットフォームごとに別のディレクトリを置きたければ、以下のようにインストールスキームを定義します:

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

また、以下のようにも指定できます、

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

`$PLAT` は、(必ずしも) 環境変数ではありません --- この表記は、Distutils がコマンドラインオプションの解釈と同じやり方で展開します。設定ファイルを解釈する際と同じです。

言うまでもないことですが、毎回新たなモジュールディストリビューションをインストールする度にインストールスキーム全体の指定を行っていては面倒です。そこで、オプションは Distutils 設定ファイル (Distutils 設定ファイル 参照) にも指定できます:

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

また、以下のようにも指定できます、

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

これら二つは、setup スクリプトを異なるインストールベースディレクトリから実行した場合には同じには ならない ので注意してください。例えば、

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

とすると、最初の書き方では pure モジュールが `/tmp/python/lib` に入り、二番目の書き方では `/tmp/lib` に入ります。(二番目のケースでは、インストールベースを `/tmp/python` に指定しようと考えるでしょう。)

読者は、設定ファイル例で、入力値に `$HOME` や `$PLAT` を使っていることに気づいているかもしれませんね。これらは Distutils の設定変数で、環境変数を彷彿とさせます。実際、この表記が使えるプラットフォーム上では、設定ファイル中に環境変数を入れられますが、 Distutils は他にも、例えば `$PLAT` のようにおそらくユーザの環境中にないような変数をいくつか持っています。(そしてもちろん、 Mac OS 9 のような環境変数のないシステムでは、設定ファイル中で使える変数は Distutils が提供しているものだけです。) 詳細は Distutils 設定ファイル を参照してください。

注釈

virtual environment 下にいる場合、仮想環境の外に不注意でプロジェクトをインストールしてしまうことを避けるために、インストールパスを変更するあらゆるオプションは distutils の全ての設定ファイルによって無視されます。

### Python サーチパスの変更

Python インタプリタが `import` 文を実行するとき、インタプリタは Python コードや拡張モジュールをモジュール検索パス中から探します。検索パスのデフォルト値は、インタプリタをビルドする際に Python のバイナリ内に設定されます。検索パスは、 `sys` を import して、 `sys.path` を出力すればわかります。

    $ 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 モジュールをインストールしたいと思うかもしれません。例えば、自分のサイトでは、 web サーバに関連する全てのソフトウェアを `/www` に置くという決まりがあるかもしれません。そこで、アドオンの Python モジュールが `/www/python` 置かれることになると、モジュールを import するためにはディレクトリを `sys.path` に追加せねばなりません。ディレクトリを検索パスに追加するには、いくつかの異なる方法が存在します。

最も手軽な方法は、パス設定ファイルをすでに Python の検索パスに含まれるディレクトリ、通常は `.../site-packages/` ディレクトリに置くというものです。パス設定ファイルは拡張子が `.pth` で、ファイルには `sys.path` に追加するパスを一行に一つづつ記述しなければなりません。 (新たなパスは今の `sys.path` の後ろに追加されるので、追加されたディレクトリ内にあるモジュールが標準のモジュールセットを上書きすることはありません。つまり、このメカニズムを使って、標準モジュールに対する修正版のインストールはできないということです。)

パスは絶対パスでも相対パスでもよく、相対パスの場合には `.pth` ファイルのあるパスからの相対になります。詳しくは `site` モジュールを参照してください。

やや便利さには欠けますが、Python の標準ライブラリ中にある `site.py` ファイルを編集することでも、 `sys.path` を変更できます。 `site.py` は、 `-S` スイッチを与えて抑制しないかぎり、Python インタープリタが実行される際に自動的に import されます。ただし、設定するには、単に `site.py` を編集して、例えば以下のような二行を加えます:

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

しかしながら、(例えば 2.2 から 2.2.2 にアップグレードするときのように) 同じメジャーバージョンの Python を再インストールすると、 `site.py` は手持ちのバージョンで上書きされてしまいます。ファイルが変更されていることを覚えておき、インストールを行う前にコピーを忘れずとっておかねばなりません。

また、 `sys.path` を修正できる二つの環境変数があります。 `PYTHONHOME` を使うと、インストールされている Python のプレフィクスを別の値に設定できます。例えば、 `PYTHONHOME` を `/www/python` に設定すると、検索パスは `['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]` といった具合になります。

`PYTHONPATH` を使うと、 `sys.path` の先頭に一連のパスを追加できます。例えば、 `PYTHONPATH` を `/www/python:/opt/py` に設定すると、検索パスは `['/www/python', '/opt/py']` から始まります。 (`sys.path` にディレクトリを追加するには、そのディレクトリが実在しなければなりません; `site` は実在しないディレクトリを除去します。)

最後に、`sys.path` はただの普通の Python のリストなので、どんな Python アプリケーションもエントリを追加したり除去したりといった修正を行えます。

## Distutils 設定ファイル

上で述べたように、Distutils 設定ファイルを使えば、任意の Distutils オプションに対して個人的な設定やサイト全体の設定を記録できます。すなわち、任意のコマンドの任意のオプションを二つか三つ (プラットフォームによって異なります) の設定ファイルに保存でき、コマンドラインを解釈する前にオプションを問い合わせさせるようにできます。つまり、設定ファイルはデフォルトの値を上書きし、さらにコマンドライン上で与えた値が設定ファイルの内容を上書きするわけです。さらに、複数の設定ファイルが適用されると、"先に" 適用されたファイルに指定されていた値は "後に" 適用されたファイル内の値で上書きされます。

### 設定ファイルの場所と名前

設定ファイルの名前と場所は、非常にわずかですがプラットフォーム間で異なります。Unix と macOS では、三種類の設定ファイルは以下のようになります (処理される順に並んでいます):

ファイルのタイプ | 場所とファイル名 | 注釈
--- | --- | ---
system | `prefix/lib/pythonver/distutils/distutils.cfg` | (1)
personal | `$HOME/.pydistutils.cfg` | (2)
local | `setup.cfg` | (3)

Windows では設定ファイルは以下のようになります:

ファイルのタイプ | 場所とファイル名 | 注釈
--- | --- | ---
system | `prefix\Lib\distutils\distutils.cfg` | (4)
personal | `%HOME%\pydistutils.cfg` | (5)
local | `setup.cfg` | (3)

全てのプラットフォームにおいて、"個人の" ファイルは `--no-user-cfg` オプションを使って一時的に無効にすることができます。

注釈:

1. 厳密に言えば、システム全体向けの設定ファイルは、 Distutils がインストールされているディレクトリになります; Unixの Python 1.6 以降では、表の通りの場所になります。 Python 1.5.2 では、 Distutils は通常 `prefix/lib/python1.5/site-packages/distutils` にインストールされるため、 Python 1.5.2 では設定ファイルをそこに置かなければなりません。

2. Unixでは、環境変数 `HOME` が定義されていない場合、標準モジュール `pwd` の `getpwuid()` 関数を使ってユーザのホームディレクトリを決定します。このとき同時に Distutils によって `os.path.expanduser()` が実行されます。

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 は標準ライブラリの一部ではありません --- 従って、システム設定ファイルは、 Windows 用の標準の Python 1.5.2 では `C:\Program Files\Python\distutils\distutils.cfg` になります。

5. Windows では、環境変数 `HOME` が設定されていない場合、 `USERPROFILE` 、 `HOMEDRIVE` 、 `HOMEPATH` を順々に試します。このとき同時に Distutils によって `os.path.expanduser()` が実行されます。

### 設定ファイルの構文

Distutils 設定ファイルは、全て同じ構文をしています。設定ファイルはセクションでグループ分けされています。各 Distutils コマンドごとにセクションがあり、それに加えて全てのコマンドに影響するグローバルオプションを設定するための `global` セクションがあります。各セクションには `option=value` の形で、一行あたり一つのオプションを指定します。

例えば、以下は全てのコマンドに対してデフォルトでメッセージを出さないよう強制するための完全な設定ファイルです:

    [global]
    verbose=0

この内容のファイルがシステム全体用の設定ファイルとしてインストールされていれば、そのシステムの全てのユーザによる全ての Python モジュール配布物に対する処理に影響します。ファイルが (個人用の設定をサポートしているシステムで) 個人用の設定ファイルとしてインストールされていれば、そのユーザが処理するモジュール配布物にのみ影響します。この内容を特定のモジュール配布物の `setup.cfg` として使えば、その配布物だけに影響します。

以下のようにして、デフォルトの "ビルドベース" ディレクトリをオーバーライドしたり、 build* コマンドが常に強制的にリビルドを行うようにもできます:

    [build]
    build-base=blib
    force=1

この設定は、コマンドライン引数の

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

に対応します。ただし、後者ではコマンドライン上で build コマンドを含めて、そのコマンドを実行するよう意味しているところが違います。特定のコマンドに対するオプションを設定ファイルに含めると、このような関連付けの必要はなくなります; あるコマンドが実行されると、そのコマンドに対するオプションが適用されます。 (また、設定ファイル内からオプションを取得するような他のコマンドを実行した場合、それらのコマンドもまた設定ファイル内の対応するオプションの値を使います。)

あるコマンドに対するオプションの完全なリストは、例えば以下のように、 `--help` を使って調べます:

    python setup.py build --help

グローバルオプションの完全なリストを得るには、コマンドを指定せずに `--help` オプションを使います:

    python setup.py --help

"Python モジュールの配布" マニュアルの、"リファレンスマニュアル" の節も参照してください。

## 拡張モジュールのビルド: 小技と豆知識

Distutils は、可能なときにはいつでも、 `setup.py` スクリプトを実行する Python インタプリタが提供する設定情報を使おうとします。例えば、拡張モジュールをコンパイルする際には、コンパイラやリンカのフラグには Python をコンパイルした際と同じものが使われます。通常、この設定はうまくいきますが、状況が複雑になると不適切な設定になることもあります。この節では、通常の Distutils の動作をオーバライドする方法について議論します。

### コンパイラ/リンカのフラグをいじるには

C や C++ で書かれた Python 拡張をコンパイルする際、しばしば特定のライブラリを使ったり、特定の種類のオブジェクトコードを生成したりする上で、コンパイラやリンカに与えるフラグをカスタマイズする必要があります。ある拡張モジュールが自分のプラットフォームではテストされていなかったり、クロスコンパイルを行わねばならない場合にはこれが当てはまります。

最も一般的なケースでは、拡張モジュールの作者はすでに拡張モジュールのコンパイルが複雑になることを見越していて、 `Setup` ファイルを提供して編集できるようにしています。 `Setup` ファイルの編集は、モジュール配布物に多くの個別の拡張モジュールがあったり、コンパイラに拡張モジュールをコンパイルさせるために細かくフラグをセットする必要があるような場合にのみ行うことになるでしょう。

`Setup` ファイルが存在する場合、ビルドするべき拡張モジュールのリストを得るために解釈されます。 `Setup` ファイルの各行には単一のモジュールを書きます。各行は以下のような構造をとります:

    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` を実行すればライブラリを追加できます。例えば、以下の行

    foo foomodule.c

で定義されたモジュールを、自分のプラットフォーム上の数学ライブラリ `libm.a` とリンクしなければならない場合、 `Setup` 内の行に `-lm` を追加するだけです:

    foo foomodule.c -lm

コンパイラやリンカ向けの任意のスイッチオプションは、 `-Xcompiler` arg や `-Xlinker` arg オプションで与えます:

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

`-Xcompiler` および `-Xlinker` の後にくるオプションは、それぞれ適切なコマンドラインに追加されます。従って、上の例では、コンパイラには `-o32` オプションが渡され、リンカには `-shared` が渡されます。コンパイラオプションに引数が必要な場合、複数の `-Xcompiler` オプションを与えます; 例えば、 `-x c++` を渡すには、 `Setup` ファイルには `-Xcompiler -x -Xcompiler c++` を渡さねばなりません。

コンパイラフラグは、環境変数 `CFLAGS` の設定でも与えられます。 `CFLAGS` が設定されていれば、 `Setup` ファイル内で指定されているコンパイラフラグに `CFLAGS` の内容が追加されます。

### Windows で非 Microsoft コンパイラを使ってビルドするには

#### Borland/CodeGear C++

この小節では、 Borland C++ コンパイラのバージョン 5.5 で Distutils を使うために必要な手順について述べています。 まず、 Borland のオブジェクトファイル形式 (OMF) は、Python 公式サイトや ActiveState の Web サイトからダウンロードできるバージョンの Python が使っている形式とは違うことを知っておかねばなりません (Python は通常、 Microsoft Visual C++ でビルドされています。Microsoft Visual C++ は COFF をオブジェクトファイル形式に使います。) このため、以下のようにして、 Python のライブラリ `python25.lib` を Borland の形式に変換する必要があります:

    coff2omf python25.lib python25_bcpp.lib

`coff2omf` プログラムは、 Borland コンパイラに付属しています。 `python25.lib` は Python インストールディレクトリの `Libs` ディレクトリ内にあります。拡張モジュールで他のライブラリ (zlib, ...) を使っている場合、それらのライブラリも変換しなければなりません。

変換されたファイルは、通常のライブラリと同じディレクトリに置かねばなりません。

さて、 Distutils は異なる名前を持つこれらのライブラリをどのように扱うのでしょうか? 拡張モジュールで (例えば `foo` という名の) ライブラリが必要な場合、 Distutils はまず `_bcpp` が後ろに付いたライブラリ (例えば `foo_bcpp.lib`) が見つかるかどうか調べ、あればそのライブラリを使います。該当するライブラリがなければ、デフォルトの名前 (`foo.lib`) を使います。 1

Borland C++ を使って Distutils に拡張モジュールをコンパイルさせるには、以下のように入力します:

    python setup.py build --compiler=bcpp

Borland C++ コンパイラをデフォルトにしたいなら、自分用、またはシステム全体向けに、 Distutils の設定ファイルを書くことを検討した方がよいでしょう (Distutils 設定ファイル 節を参照してください)。

参考

C++Builder Compiler

  Borland によるフリーの C++ コンパイラに関する情報で、コンパイラのダウンロードページへのリンクもあります。

Creating Python Extensions Using Borland's Free Compiler

  Borland 製のフリーのコマンドライン C++ を使って Python をビルドする方法について述べたドキュメントです。

#### GNU C / Cygwin / MinGW

この節では、Cygwin や MinGW 2 配布物中の GNU C/C++ コンパイラで Distutils を使うために必要な手順について述べます。Cygwin 向けにビルドされている Python インタプリタを使っているなら、以下の手順をとらなくても Distutils はまったく問題なく動作します。

全ての拡張ライブラリが MinGW や Cygwin でビルドできるわけではありませんが、多くの場合はビルドできます。ビルドできない拡張ライブラリは、大抵C++を利用していたり Microsoft Visual Cの拡張に依存していたりします。

distutils に Cygwin を使って拡張をコンパイルさせるには次のようにタイプします:

    python setup.py build --compiler=cygwin

Cygwin を no-cygwin モード 3 で使うときや MinGW を使うときは次のようにします:

    python setup.py build --compiler=mingw32

これらのオプションやコンパイラをデフォルトにしたい場合、 Distutils の個人用あるいはシステム全体用の設定ファイルを書くことを検討するべきです。 (Distutils 設定ファイル を参照してください)

##### 古いバージョンの Python と MinGW

以下の手順は Python 2.4.1 以前と MinGW 3.0.0 (binutils-2.13.90-20030111-1) 以前を利用しているときのものです。

上記のコンパイラは、いくつかの特殊なライブラリを必要とします。この作業は Borland の C++ よりもやや複雑です。というのは、ライブラリを変換するためのプログラムが存在しないからです。 まず、 Python DLL が公開している全てのシンボルからなるリストを作成しなければなりません。 (この作業むけの良いプログラムは、 https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/ から入手できます。)

    pexports python25.dll >python25.def

インストールされた `python25.dll` の位置はインストールオプションと、 Windowsのバージョンと言語に依存します。"自分だけのため"のインストールの場合には、インストールディレクトリのルートに配置されます。共有インストールの場合にはシステムディレクトリに配置されます。

これで、上で得られた情報をもとに、gcc 用の import ライブラリを作成できます。

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

出来上がったライブラリは、 `python25.lib` と同じディレクトリに置かなければなりません。 (Python インストールディレクトリの `libs` ディレクトリになるはずです。)

拡張モジュールが他のライブラリ (zlib, ...) を必要とする場合、それらのライブラリも変換しなければなりません。変換されたファイルは、それぞれ通常のライブラリが置かれているのと同じディレクトリに置かねばなりません。

参考

Building Python modules on MS Windows platform with MinGW

  MinGW 環境で必要なライブラリのビルドに関する情報があります。

脚注

1

  つまり、全ての既存の COFF ライブラリを同名の OMF ライブラリに置き換えてもかまわないということです。

2

  より詳細な情報については https://www.sourceware.org/cygwin/ を参照して下さい。

3

  このモードでは POSIX エミュレーションを利用できませんが、 `cygwin1.dll` も必要なくなります。