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.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.
仮想環境¶
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 andPYTHONHOME
is not set, this path is used instead of the path to the main executable when deducingprefix
andexec_prefix
.
_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 を使う を参照。