【Python】VSCodeでのPYTHONPATH設定ガイド

vscodeでpythonの開発を行う場合のPYTHONPATHをvscodeに認識させる方法と
その影響範囲についてまとめる。

PYTHONPATHについては下記記事で書いている

【Python】PYTHONPATHって何？

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

vscodeにPYTHONPATHを読み込ませるメリット

vscodeにPYTHONPATHを読み込ませることでVSCodeの補完・解析・拡張機能にPYTHONPATHを反映させることができる
具体的には

• importエラーの解消
• vscode上でのpytestの実施

などがある。

vscodeにPYTHONPATHを読み込ませる方法

vscodeにPYTHONPATHを読み込ませるためには

1. Python拡張機能のインストール
2. .envファイルの作成
3. .vscode/setting.jsonの設定※.envファイルの格納位置によっては不要

が必要になる。

また上記３で書いたように.envファイルの格納位置によって少し設定が変わるので
それぞれ解説する。

プロジェクトのルート直下に置く場合

.envをプロジェクト直下に置く場合の手順。
プロジェクト構成としては下記のようなイメージ

Copy
my-project/
├── app/
│   └── main.py
├── tests/
│   └── test_main.py
└── .env

各ファイルは下記にする

main.py

Copy
# app/main.py

def greet(name: str) -> str:
    return f"Hello, {name}!"

test_main.py

Copy
# tests/test_main.py

import unittest
# from app.main import greet  
from main import greet  # PYTHONPATHが通っていればこれでOK

class TestMain(unittest.TestCase):
    def test_greet(self):
        self.assertEqual(greet("World"), "Hello, World!")

if __name__ == "__main__":
    unittest.main()

• PYTHONPATHが通っていないとvscode上でimportエラーになる

Python拡張機能のインストール

vscodeでpython拡張機能をインストールする
拡張機能があればプロジェクトルートに置いた.envは自動で読み込んでくれる
※vscode本体だけでは.envを認識しない。

.envファイルの作成

Copy
PYTHONPATH=./app

• この設定でapp配下はどのモジュールからでも「app」を省略してimportできる

別の場所（例：.vscodeフォルダ）に置く場合

.envをプロジェクト直下ではなく、仮に.vscode/フォルダに置く場合の手順
プロジェクト構成としては下記のようなイメージ

Copy
my-project/
├── app/
│   └── main.py
├── tests/
│   └── test_main.py
└── .vscode/
    ├── .env
    └── settings.json

各ファイルは下記にする

main.py

Copy
# app/main.py

def greet(name: str) -> str:
    return f"Hello, {name}!"

test_main.py

Copy
# tests/test_main.py

import unittest
# from app.main import greet  
from main import greet  # PYTHONPATHが通っていればこれでOK

class TestMain(unittest.TestCase):
    def test_greet(self):
        self.assertEqual(greet("World"), "Hello, World!")

if __name__ == "__main__":
    unittest.main()

• PYTHONPATHが通っていないとvscode上でimportエラーになる

Python拡張機能のインストール

vscodeでpython拡張機能をインストールする
.envファイルがプロジェクトルートにないので、これだけではimportエラーが発生する

.envファイルの作成

Copy
PYTHONPATH=./app

• この設定でapp配下はどのモジュールからでも「app」を省略してimportできる

.vscode/settings.jsonの作成

Copy
{
  "python.envFile": "${workspaceFolder}/.vscode/.env",
}

• settings.jsonにpython.envFileを明示的に指定する必要あり。
• これにより、VSCodeのPython拡張機能が .vscode/.envを読み込むようになる。

.env読み込みのまとめ

• .envを使うなら Python拡張機能は必須。
• .envがルートにあるなら、通常は自動で読み込まれる。
• .envがルート以外にある場合は.vscode/settings.jsonで "python.envFile" を設定する。
• 安全にいくなら.vscode/settings.jsonで "python.envFile" を設定すると確実

実行時の挙動について

vscodeで

• 「Pythonファイルを右クリック → 'Pythonファイルを実行'」や「コードレンズから実行」

を使った場合、vscodeが内部的にpythonコマンドを直接呼び出しているため
.envは読み込まれない。 ※vscodeのターミナルで実行した場合も同様。

.envを読み込んで実行するには？

vscode上で実行したいなら、launch.jsonを作って実行するしかない。

Copy
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run main.py with PYTHONPATH",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/app/main.py",
            "envFile": "${workspaceFolder}/.env",
            "console": "integratedTerminal"
        }
    ]
}

• envFileには実際の.envのパスを入れる

まとめ

「VSCodeが.envを読み込む」
→ VSCodeの補完・解析・拡張機能のため

「実行時に.envを読み込む」
→ Pythonの実行環境に環境変数を渡すため

のようにvscodeに.envを認識させてもvscode上で使えるようになるだけであって
実行時に.envを読んでいるわけではない。

この2つはまったく別のレイヤーの話になっているので注意する

ちなみにpytestをvscodeの拡張機能を使ってvscode上で行う場合は、vscode上から実行するので
PYTHONPATHは認識される。
pytestをvscodeで実行する方法については下記記事でまとめている

【Docker × VScode × pytest 】pytestの環境別実行方法

VSCodeでpytestを「 ローカルで実行する」または「コンテナ上で実行する」方法を調べたので忘備録として残す