できない.dev

sys.path

別名: PYTHONPATH / モジュール検索パス / module search path

sys.path は、Python が import するモジュールを探すディレクトリの一覧である。
起動時にスクリプトの場所、環境変数 PYTHONPATH、標準ライブラリ、site-packages の順で組み立てられる。

公開:

定義

sys.path は、Python が import したモジュールを探すディレクトリを並べたリストである。
Python は先頭から順に探し、最初に見つかったものを読み込む。
どのディレクトリにも無ければ ModuleNotFoundError になる。

詳細

起動時の先頭には、python script.py ならスクリプトのあるディレクトリが入る。
python -m や対話モードでは、今いるディレクトリが入る。
その後ろに環境変数 PYTHONPATH の内容、標準ライブラリ、site-packages が続く。
組み立ての順番は公式ドキュメント(新しいタブで開く)に書かれている。

pytest は既定の prepend モードで、テストファイルを読み込むために、そのディレクトリを sys.path の先頭に足す。
プロジェクト直下の自作モジュールは、この仕組みだけではテストから見えないことがある。
設定ファイルの pythonpath に場所を書けば、pytest がそのディレクトリも先頭に足す。

よくある誤解

sys.path は、今いるディレクトリを常に含むわけではない。
python tests/test_app.py のようにスクリプトとして起動すると、先頭に入るのは tests で、今いるディレクトリは入らない。
コード中に sys.path.append() を書けば動くが、起動の仕方を変えると壊れる。
PYTHONPATH はインストールしたすべての Python に効くので、シェルの設定に書くと別の環境まで巻き込む。

関連

pytest で自作モジュールが見つからない例は pytest でテストから自作モジュールを import できない(ModuleNotFoundError) にある。
パッケージの区切りは __init__.py、隔離した環境は venv で説明している。