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

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

The first entry in the module search path is the directory that contains the input script, if there is one. Otherwise, the first entry is the current directory, which is the case when executing the interactive shell, a `-c` command, or `-m` module.

The `PYTHONPATH` environment variable is often used to add directories to the search path. If this environment variable is found then the contents are added to the module search path.

注釈

`PYTHONPATH` will affect all installed Python versions/environments. Be wary of setting this in your shell profile or global environment variables. The `site` module offers more nuanced techniques as mentioned below.

The next items added are the directories containing standard Python modules as well as any extension modules that these modules depend on. Extension modules are `.pyd` files on Windows and `.so` files on other platforms. The directory with the platform-independent Python modules is called `prefix`. The directory with the extension modules is called `exec_prefix`.

The `PYTHONHOME` environment variable may be used to set the `prefix` and `exec_prefix` locations. Otherwise these directories are found by using the Python executable as a starting point and then looking for various 'landmark' files and directories. Note that any symbolic links are followed so the real Python executable location is used as the search starting point. The Python executable location is called `home`.

Once `home` is determined, the `prefix` directory is found by first looking for `pythonmajorversionminorversion.zip` (`python311.zip`). On Windows the zip archive is searched for in `home` and on Unix the archive is expected to be in `lib`. Note that the expected zip archive location is added to the module search path even if the archive does not exist. If no archive was found, Python on Windows will continue the search for `prefix` by looking for `Lib\os.py`. Python on Unix will look for `lib/pythonmajorversion.minorversion/os.py` (`lib/python3.11/os.py`). On Windows `prefix` and `exec_prefix` are the same, however on other platforms `lib/pythonmajorversion.minorversion/lib-dynload` (`lib/python3.11/lib-dynload`) is searched for and used as an anchor for `exec_prefix`. On some platforms `lib` may be `lib64` or another value, see `sys.platlibdir` and `PYTHONPLATLIBDIR`.

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

If `PYTHONHOME` is not set, and a `pyvenv.cfg` file is found alongside the main executable, or in its parent directory, `sys.prefix` and `sys.exec_prefix` get set to the directory containing `pyvenv.cfg`, otherwise they are set to the same value as `sys.base_prefix` and `sys.base_exec_prefix`, respectively. This is used by Virtual Environments.

Finally, the `site` module is processed and `site-packages` directories are added to the module search path. The `PYTHONUSERBASE` environment variable controls where is searched for user site-packages and the `PYTHONNOUSERSITE` environment variable prevents searching for user site-packages all together. A common way to customize the search path is to create `sitecustomize` or `usercustomize` modules as described in the `site` module documentation.

注釈

The command line options `-E`, `-P`, `-I`, `-S` and `-s` further affect path calculations, see their documentation for details.

バージョン 3.14 で変更: `sys.prefix` and `sys.exec_prefix` are now set to the `pyvenv.cfg` directory during the path initialization. This was previously done by `site`, therefore affected by `-S`.

## Virtual Environments

Virtual environments place a `pyvenv.cfg` file in their prefix, which causes `sys.prefix` and `sys.exec_prefix` to point to them, instead of the base installation.

The `prefix` and `exec_prefix` values of the base installation are available at `sys.base_prefix` and `sys.base_exec_prefix`.

As well as being used as a marker to identify virtual environments, `pyvenv.cfg` may also be used to configure the `site` initialization. Please refer to `site`'s virtual environments documentation.

注釈

`PYTHONHOME` overrides the `pyvenv.cfg` detection.

注釈

There are other ways "virtual environments" could be implemented. This documentation refers to implementations based on the `pyvenv.cfg` mechanism, such as `venv`, that many virtual environment implementations follow.

## _pth files

To completely override `sys.path` create a `._pth` file with the same name as the shared library or executable (`python._pth` or `python311._pth`). The shared library path is always known on Windows, however it may not be available on other platforms. In the `._pth` file specify one line for each path to add to `sys.path`. The file based on the shared library name overrides the one based on the executable, which allows paths to be restricted for any program loading the runtime if desired.

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

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

## 埋め込みの Python

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

参考

- Windows の詳細についてのメモは、 モジュールの検索 を参照。

- Unix の詳細は、 Unix プラットフォームで Python を使う を参照。