【Python】PYTHONPATHって何？

pythonで開発を始めて最初らへんによくモジュールのimportエラーに
引っかかった。

調べると「PYTHONPATHが～」的なことを言われるので
「PYTHONPATH」について調べてまとめておく

PYTHONPATHとは？

PYTHONPATHは、Pythonが

• モジュール
• パッケージ

探すときの検索パスを追加で指定する環境変数のこと。
importしているモジュールを検索する時に使用される

モジュールとは？

モジュールはpyファイルのこと。
Pythoスクリプトとも呼ばれる

パッケージとは？

パッケージとは 複数のモジュールをまとめた__init__.py ファイルが含まれるディレクトリのこと。 パッケージはディレクトリ単位でimportできる

Pythonのモジュール検索の仕組み

モジュールでimportをするとき、Pythonは次の順番でモジュールを探す

1. スクリプトがあるディレクトリ
2. 組み込み標準ライブラリのディレクトリ
3. サードパーティライブラリのディレクトリ（site-packages）
4. PYTHONPATHに指定したディレクトリ
5. sys.path に書かれたその他のパス

PYTHONPATHはこの「4番目」にあたり、標準の検索パスに自分の好きなディレクトリを追加できる。
※当記事ではPYTHONPATHをメインで解説するため、上記の1~5のうち2,3,5は割愛する

モジュール検索の挙動

例えば

Copy
my_project/
├── src/
│   └── utils.py
└── main.py

のようなプロジェクト構成で

src/utils.py

Copy
def greet() -> str:
    return "Hello, world!"

main.py

Copy
from src.utils import greet

def main() -> None:
    print(greet())

if __name__ == "__main__":
    main()

• utilsまでのフルパスを指定

のようなモジュールの場合
検索の流れ（python main.pyをmy_projectで実行）としては

1. Python インタプリタが「スクリプトがあるディレクトリ (my_project)」を探索
2. その配下に src ディレクトリがあるので次に進む
3. src/utils.py を発見
4. その中に greet があるので import 成功 ※PYTHONPATH の指定は不要

のようになる。

実行結果

my_projectで実行

Copy
$ python main.py
Hello, world!

パッケージについて

このプロジェクト構成ではsrc配下に__init__.pyがなくても
パッケージとして認識されているので

Copy
from src.utils import greet

の形でimportできてる。
Python 3.3以降では、PEP 420 によって「namespace package（名前空間パッケージ）」という仕組みが導入されたため
__init__.pyがなくてもディレクトリをパッケージとして扱えるようになっている。
※実務では __init__.pyを置いておくのがベター。

PYTHONPATHを設定する場合

同じディレクトリ構成で、PYTHONPATHを指定することでimportに
起点からフルパスを書かなくても実行するようにできる。

src/utils.py

Copy
def greet() -> str:
    return "Hello, world!"

main.py

Copy
from utils import greet

def main() -> None:
    print(greet())

if __name__ == "__main__":
    main()

• srcを削除

のようなモジュールで、PYTHONPATHに下記を指定した場合

Copy
PYTHONPATH=./src

検索の流れ（同じく my_project で実行）としては

1. Pythonインタプリタがmy_projectを探索 → 直下にutils.pyは存在しない
2. 標準ライブラリ・site-packagesを探索 → 該当なし
3. 環境変数 PYTHONPATH=./src が指定されているので、その配下を探索
4. src/utils.pyを発見、greet をロード ※PYTHONPATHがある場合のみimport成功

のようになる

実行結果

my_projectで実行

Copy
$ PYTHONPATH=./src python main.py
Hello, world!

• 一時的に実行時にPYTHONPATHを指定してから実行する

もしくは

Copy
$ export PYTHONPATH=./src

$ echo $PYTHONPATH
./src

lunaj@TABLET-FGJE15R7 MINGW64 /c/develop/01_TechSamples/Python/PythonOrg/my_project
$ python main.py
Hello, world!

• ターミナル上でPYTHONPATHを永続化してから実行する※ターミナルを閉じると消える

サブフォルダは自動で検索対象にならないことに注意！

Python インタプリタが「スクリプトがあるディレクトリ (my_project)」を探索するとき、
その直下のみがモジュール検索対象になります。

つまり

• my_project 直下にあるmain.pyやutils.pyなどのモジュールは探索される
• しかし src/のようなサブフォルダは探索されない

したがってsrcを探索対象にしたい場合は

• import src.utilsのようにフルパスで指定する
• または PYTHONPATH=./srcを設定する

のいずれかが必要になる

PYTHONPATHを複数設定

PYTHONPATHを複数設定することもできる。

Copy
my_project/
├── src/
├── lib/
├── common/
└── main.py

この場合、main.py から src, lib, common のモジュールを使いたければ、
それぞれを下記のようにPYTHONPATHに追加する必要がある。

Copy
PYTHONPATH=./src:./lib:./common

あまり使うことはなさそうだが。。。。

PYTHONPATHまとめ

• サブフォルダは自動では検索対象にならないため、PYTHONPATHで明示的に追加するか、フルパスでimportする必要がある
• PYTHONPATHに指定したディレクトリはモジュール検索の対象となる
• PYTHONPATHに指定したディレクトリが起点となり、その配下のモジュール、パッケージはimport可能になる。※フルパスを省略できる