sys.path モジュール検索パスの初期化

モジュール検索パスは Python の開始時に初期化されます。このモジュール検索パスは、 sys.path でアクセス可能です。

実行するスクリプトがある場合、モジュール検索パスの最初の項目は、そのスクリプトがあるディレクトリです。 そうでなければ最初の項目はカレントディレクトリです。 対話型シェル、-c コマンド、-m モジュールを実行する場合がこれに当たります。

PYTHONPATH 環境変数は、検索パスにディレクトリを追加するためによく使われます。 この環境変数が見つかると、その内容をモジュール検索パスに追加します。

注釈

PYTHONPATH は、インストールされているすべての Python のバージョンと環境に影響します。 シェルのプロファイルやグローバルな環境変数で設定する場合は注意してください。 後述するように、site モジュールではより細かな方法で設定できます。

次に、標準の Python モジュールと、それらが依存する 拡張モジュール を含むディレクトリを追加します。 拡張モジュールは Windows では .pyd ファイル、ほかのプラットフォームでは .so ファイルです。 プラットフォームに依存しない Python モジュールのあるディレクトリを prefix、拡張モジュールのあるディレクトリを exec_prefix と呼びます。

PYTHONHOME 環境変数で prefix と exec_prefix の場所を設定できます。 設定されていなければ、Python 実行ファイルを起点に、目印となる各種のファイルやディレクトリを探して、これらのディレクトリを特定します。 シンボリックリンクはたどるため、検索の起点は Python 実行ファイルの実際の場所になります。 Python 実行ファイルの場所を home と呼びます。

home が決まると、まず pythonmajorversionminorversion.zip (python311.zip) を探して prefix ディレクトリを特定します。 Windows では home 内を探し、Unix では lib 内にアーカイブがあると想定します。 アーカイブが存在しなくても、想定される zip アーカイブの場所はモジュール検索パスに追加されます。 アーカイブが見つからなければ、Windows の Python は Lib\os.py を探して prefix の検索を続けます。 Unix の Python は lib/pythonmajorversion.minorversion/os.py (lib/python3.11/os.py) を探します。 Windows では prefix と exec_prefix は同じですが、ほかのプラットフォームでは lib/pythonmajorversion.minorversion/lib-dynload (lib/python3.11/lib-dynload) を探し、exec_prefix を特定する基準にします。 プラットフォームによっては lib が lib64 や別の値になる場合があります。 sys.platlibdir と PYTHONPLATLIBDIR を参照してください。

見つかった prefix と exec_prefix は、それぞれ sys.base_prefix と sys.base_exec_prefix で取得できます。

PYTHONHOME が設定されておらず、メインの実行ファイルと同じディレクトリか、その親ディレクトリに pyvenv.cfg が見つかると、 sys.prefix と sys.exec_prefix は pyvenv.cfg のあるディレクトリに設定されます。 そうでなければ、それぞれ sys.base_prefix と sys.base_exec_prefix と同じ値になります。 これは 仮想環境 で利用されます。

最後に site モジュールを処理し、site-packages ディレクトリをモジュール検索パスに追加します。 PYTHONUSERBASE 環境変数はユーザーの site-packages を探す場所を制御し、PYTHONNOUSERSITE 環境変数はユーザーの site-packages の検索を完全に無効にします。 検索パスをカスタマイズする一般的な方法は、site モジュールのドキュメントで説明されているように、sitecustomize モジュールや usercustomize モジュールを作成することです。

注釈

コマンドラインオプション -E、-P、-I、-S、-s もパスの算出に影響します。 詳しくは各オプションのドキュメントを参照してください。

バージョン 3.14 で変更: sys.prefix と sys.exec_prefix は、パスの初期化時に pyvenv.cfg のあるディレクトリに設定されるようになりました。 以前は site が行っていたため、-S の影響を受けていました。

仮想環境

仮想環境は、そのプレフィックスに pyvenv.cfg ファイルを置きます。 これにより、sys.prefix と sys.exec_prefix は基となるインストール先ではなく、仮想環境を指します。

基となるインストール先の prefix と exec_prefix は、sys.base_prefix と sys.base_exec_prefix で取得できます。

pyvenv.cfg は仮想環境を識別する目印として使われるだけでなく、site の初期化の設定にも使えます。 site の 仮想環境のドキュメント を参照してください。

注釈

PYTHONHOME は pyvenv.cfg の検出より優先されます。

注釈

「仮想環境」を実装する方法はほかにもあります。 ここで説明するのは venv などの pyvenv.cfg の仕組みに基づく実装で、多くの仮想環境の実装がこの方式に従っています。

_pth ファイル

sys.path を完全に上書きするには、共有ライブラリや実行ファイルと同じ名前の ._pth ファイル (python._pth や python311._pth) を作成します。 Windows では共有ライブラリのパスは常に分かりますが、ほかのプラットフォームでは取得できない場合があります。 ._pth ファイルでは、sys.path に追加するパスを 1 行に 1 つずつ指定します。 共有ライブラリ名に基づくファイルは、実行ファイル名に基づくファイルより優先されます。 これにより、必要ならランタイムを読み込むあらゆるプログラムのパスを制限できます。

ファイルが存在したときは、全てのレジストリと環境変数は無視され、隔離モードになり、そのファイルに import site と指定していない限りは site はインポートされません。 空行と # で始まる行は無視されます。 それぞれのパスには絶対パスか、このファイルの場所を基準とした相対パスを指定できます。 site 以外のインポート文は許可されておらず、任意のコードも書けません。

import site を指定したときは、(アンダースコアが前に付かない) .pth ファイルは site モジュールにより通常通り処理されることに注意してください。

埋め込みの Python

Python が他のアプリケーションに埋め込まれている場合は、 Py_InitializeFromConfig() と PyConfig 構造体が Python の初期化に使用可能です。パス固有の詳細は、 Python のパス設定 で説明されています。

参考