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

Author:

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

このドキュメントでは、 Python モジュール配布ユーティリティ (Python Distribution Utilities, “Distutils”) について、 エンドユーザの視点に立ち、サードパーティ製のモジュールや拡張モジュールの構築やインストールによって標準の Python に機能を追加する方法について述べます。

注釈

This guide only covers the basic tools for installing extensions that are provided as part of this version of Python. Third party tools offer easier to use and more secure alternatives. Refer to the quick recommendations section in the Python Packaging User Guide for more information.

はじめに

Python の広範な標準ライブラリは、プログラミングにおける多くの要求をカバーしていますが、時には何らかの新たな機能をサードパーティ製モジュールの形で追加する必要に迫られます。自分がプログラムを書くときのサポートとして必要な場合もあるし、自分が使いたいアプリケーションがたまたま Python で書かれていて、そのサポートとして必要な場合もあるでしょう。

以前は、すでにインストール済みの Python に対して、サードパーティ製モジュールを追加するためのサポートはほとんどありませんでした。しかしPython 配布ユーティリティ (Python Distribution Utilities, 略して Distutils) が Python 2.0 から取り入れられ、状況は変わりました。

This document is aimed primarily at the people who need to install third-party Python modules: end-users and system administrators who just need to get some Python application running, and existing Python programmers who want to add some new goodies to their toolbox. You don’t need to know Python to read this document; there will be some brief forays into using Python’s interactive mode to explore your installation, but that’s it. If you’re looking for information on how to distribute your own Python modules so that others may use them, see the Python モジュールの配布 manual. setup スクリプトをデバッグする may also be of interest.

もっとも簡単な場合: ありふれたインストール作業

最も楽なのは、インストールしたいモジュール配布物の特殊なバージョンをインストールしたいプラットフォーム向けに誰かがすでに用意してくれていて、他のアプリケーションと同じようにインストールするだけであるような場合です。例えば Windows ユーザ向けには実行可能形式のインストーラ、 RPM ベースの Linux システム (Red Hat, SuSE, Mandrake その他多数) 向けには RPM パッケージ、 Debian ベースの Linux システム向けには Debian パッケージといった具合に、モジュール開発者はビルド済み配布物を作成しているかもしれません。

その場合、自分のプラットフォームに適したインストーラをダウンロードして、例えば RPM なら rpm --install などの方法でインストーラを実行します。 Python や setup スクリプトを実行する必要も、何かをコンパイルする必要もありません。 — 何らかの手順書を一切読まずにインストールすることも可能でしょう (常に読んだほうが良いですが)。

もちろん、いつもこう簡単とは限りません。自分のプラットフォーム向けのお手軽なインストーラがないモジュール配布物に興味を持つこともあるでしょう。そんな場合には、モジュールの作者やメンテナがリリースしているソース配布物から作業をはじめねばなりません。ソース配布物からのインストールは、モジュールが標準的な方法でパッケージ化されている限りさほど大変ではありません。このドキュメントの大部分は、標準的なソース配布物からのビルドとインストールに関するものです。

新しい標準: Distutils

If you download a module source distribution, you can tell pretty quickly if it was packaged and distributed in the standard way, i.e. using the Distutils. First, the distribution’s name and version number will be featured prominently in the name of the downloaded archive, e.g. foo-1.0.tar.gz or widget-0.9.7.zip. Next, the archive will unpack into a similarly-named directory: foo-1.0 or widget-0.9.7. Additionally, the distribution will contain a setup script setup.py, and a file named README.txt or possibly just README, which should explain that building and installing the module distribution is a simple matter of running one command from a terminal:

python setup.py install

For Windows, this command should be run from a command prompt window (Start ‣ Accessories):

setup.py install

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

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

As described in section 新しい標準: Distutils, building and installing a module distribution using the Distutils is usually one simple command to run from a terminal:

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

On Windows, you’d probably download foo-1.0.zip. If you downloaded the archive file to C:\Temp, then it would unpack into C:\Temp\foo-1.0; you can use either a archive manipulator with a graphical user interface (such as WinZip) or a command-line tool (such as unzip or pkunzip) to unpack the archive. Then, open a command prompt window and run:

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 directory) に置く働きがあります。デフォルトでは、ビルドディレクトリは配布物ルート下の 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 をベースとしたMac OS X) では、インストールしようとするモジュール配布物が pure Python なのか、拡張モジュールを含む (“非 pure”) のかによっても異なります:

プラットフォーム

標準のインストール場所

デフォルト値

注釈

Unix (pure) prefix/lib/pythonX.Y/site-packages /usr/local/lib/pythonX.Y/site-packages (1)
Unix (non-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 では普通、 prefixexec-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と Mac OS X でもほぼ常に同じです。自分の Python がどんな prefixexec-prefix を使っているかは、Python を対話モードで起動して、単純なコマンドをいくつか入力すればわかります。 Windows では、 スタート ‣ (すべての) プログラム ‣ Python X.Y ‣ Python (command line) を選びます。 Mac OS 9 では、 PythonInterpreter を起動します。インタプリタを起動すると、プロンプトに Python コードを入力できます。例えば、作者の使っている Linux システムで、三つの Python 文を以下のように入力すると、出力から作者のシステムの prefixexec-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'

A few other placeholders are used in this document: X.Y stands for the version of Python, for example 3.2; abiflags will be replaced by the value of sys.abiflags or the empty string for platforms which don’t define ABI flags; distname will be replaced by the name of the module distribution being installed. Dots and capitalization are important in the paths; for example, a value that uses python3.2 on UNIX will typically use Python32 on Windows.

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

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

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

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

Note that the various alternate installation schemes are mutually exclusive: you can pass --user, or --home, or --prefix and --exec-prefix, or --install-base and --install-platbase, but you can’t mix from these groups.

Alternate installation: the user scheme

This scheme is designed to be the most convenient solution for users that don’t have write permission to the global site-packages directory or don’t want to install into it. It is enabled with a simple option:

python setup.py install --user

Files will be installed into subdirectories of site.USER_BASE (written as userbase hereafter). This scheme installs pure Python modules and extension modules in the same location (also known as site.USER_SITE). Here are the values for UNIX, including Mac OS X:

Type of file Installation directory
modules userbase/lib/pythonX.Y/site-packages
scripts userbase/bin

データ

userbase

C ヘッダー

userbase/include/pythonX.Yabiflags/distname

And here are the values used on Windows:

Type of file Installation directory
modules userbase\PythonXY\site-packages
scripts userbase\Scripts

データ

userbase

C ヘッダー

userbase\PythonXY\Include\distname

The advantage of using this scheme compared to the other ones described below is that the user site-packages directory is under normal conditions always included in sys.path (see site for more information), which means that there is no additional step to perform after running the setup.py script to finalize the installation.

The build_ext command also has a --user option to add userbase/include to the compiler search path for header files and userbase/lib to the compiler search path for libraries as well as to the runtime search path for shared C libraries (rpath).

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

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

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

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

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

python setup.py install --home=~

To make Python find the distributions installed with this scheme, you may have to modify Python’s search path or edit sitecustomize (see site) to call site.addsitedir() or edit sys.path.

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

Type of file Installation directory
modules home/lib/python
scripts home/bin

データ

home

C ヘッダー

home/include/python/distname

(Mentally replace slashes with backslashes if you’re on Windows.)

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

The “prefix scheme” is useful when you wish to use one Python installation to perform the build/install (i.e., to run the setup script), but install modules into the third-party module directory of a different Python installation (or something that looks like a different Python installation). If this sounds a trifle unusual, it is—that’s why the user and home schemes come before. However, there are at least two known cases where the prefix scheme will be useful.

まず、多くの 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 になります。ファイルは以下のようにインストールされます:

Type of file Installation directory
Python modules prefix/lib/pythonX.Y/site-packages
extension modules exec-prefix/lib/pythonX.Y/site-packages
scripts prefix/bin

データ

prefix

C ヘッダー

prefix/include/pythonX.Yabiflags/distname

--prefix--exec-prefix が実際に他のインストール済み Python の場所を指している必要はありません; 上に挙げたディレクトリがまだ存在しなければ、インストール時に作成されます。

ちなみに、prefix スキームが重要な本当の理由は、単に標準の Unix インストールが prefix スキームを使っているからです。ただし、そのときには、 --prefix--exec-prefix は Python 自体が sys.prefixsys.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 ディレクトリにインストールします。

The installation base is defined by the --prefix option; the --exec-prefix option is not supported under Windows, which means that pure Python modules and extension modules are installed into the same location. Files are installed as follows:

Type of file Installation directory
modules prefix\Lib\site-packages
scripts prefix\Scripts

データ

prefix

C ヘッダー

prefix\Include\distname

カスタムのインストール

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

To create a custom installation scheme, you start with one of the alternate schemes and override some of the installation directories used for the various types of files, using these options:

Type of file Override option
Python modules --install-purelib
extension modules --install-platlib
all modules --install-lib
scripts --install-scripts

データ

--install-data

C ヘッダー

--install-headers

These override options can be relative, absolute, or explicitly defined in terms of one of the installation base directories. (There are two installation base directories, and they are normally the same— they only differ when you use the Unix “prefix scheme” and supply different --prefix and --exec-prefix options; using --install-lib will override values computed or given for --install-purelib and --install-platlib, and is recommended for schemes that don’t make a difference between Python and extension modules.)

例えば、 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 になります。)

If you maintain Python on Windows, you might want third-party modules to live in a subdirectory of prefix, rather than right in prefix itself. This is almost as easy as customizing the script installation directory —you just have to remember that there are two types of modules to worry about, Python and extension modules, which can conveniently be both controlled by one option:

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

The specified installation directory is relative to prefix. Of course, you also have to ensure that this directory is in Python’s module search path, such as by putting a .pth file in a site directory (see site). See section Python サーチパスの変更 to find out how to modify Python’s search path.

インストールスキーム全体を定義したいのなら、全てのインストールディレクトリオプションを指定しなければなりません。この作業には、相対パスを使った指定を勧めます; 例えば、全ての 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

would install pure modules to /tmp/python/lib in the first case, and to /tmp/lib in the second case. (For the second case, you probably want to supply an installation base of /tmp/python.)

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

注釈

When a virtual environment is activated, any options that change the installation path will be ignored from all distutils configuration files to prevent inadvertently installing projects outside of the virtual environment.

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 と Mac OS X では、三種類の設定ファイルは以下のようになります (処理される順に並んでいます):

Type of file

場所とファイル名

注釈

system prefix/lib/pythonver/distutils/distutils.cfg (1)
personal $HOME/.pydistutils.cfg (2)
local setup.cfg (3)

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

Type of file

場所とファイル名

注釈

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 が定義されていない場合、標準モジュール pwdgetpwuid() 関数を使ってユーザのホームディレクトリを決定します。このとき同時に 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 が設定されていない場合、 USERPROFILEHOMEDRIVEHOMEPATH を順々に試します。このとき同時に 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) 以前を利用しているときのものです。

These compilers require some special libraries. This task is more complex than for Borland’s C++, because there is no program to convert the library. First you have to create a list of symbols which the Python DLL exports. (You can find a good program for this task at http://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]

詳しくは http://sources.redhat.com/cygwin/http://www.mingw.org/ を参照してください

[3]

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