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 を参照してください。

Once found, prefix and exec_prefix are available at sys.prefix and sys.exec_prefix respectively.

Finally, the site module is processed and site-packages directories are added to the module search path. A common way to customize the search path is to create sitecustomize or usercustomize modules as described in the site module documentation.

注釈

Certain command line options may further affect path calculations. See -E, -I, -s and -S for further details.

Virtual environments

If Python is run in a virtual environment (as described at 仮想環境とパッケージ) then prefix and exec_prefix are specific to the virtual environment.

If a pyvenv.cfg file is found alongside the main executable, or in the directory one level above the executable, the following variations apply:

  • If home is an absolute path and PYTHONHOME is not set, this path is used instead of the path to the main executable when deducing prefix and exec_prefix.

_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 のパス設定 で説明されています。

参考