🔍 Pythonのモジュールが「見つからない」と言われる理由と仮想環境の仕組み
はじめに
Python でコードを書いていて、こんなエラーに遭遇したことはありませんか？
Import "foo" could not be resolved
モジュールが正しくインストールされているはずなのに、なぜか見つからない。
これは、「インタプリタの違い」と「モジュール探索パス（sys.path）の仕組み」を理解すれば納得できます。
モジュールのインポートの基本構造
Python でモジュールをインポートする際、次のように書きます。
import foo
このとき Python は、内部で「autogen という名前のモジュールやパッケージがどこにあるか」を探索します。この探索は、Python の モジュール探索パス である sys.path というリストに基づいて行われます。
このリストには、以下のようなパスが含まれています：
・現在の作業ディレクトリ
・標準ライブラリのディレクトリ
・site-packages（pipでインストールされたモジュールの保存場所）
・仮想環境が使われている場合は、その仮想環境内のパス
モジュールが「見つからない」と言われる原因
- 仮想環境とグローバル環境の違い
多くの場合、「モジュールが見つからない」エラーは、違う環境で Python を実行していることが原因です。
たとえば：
ターミナルで pip install foo したが、VSCode の実行環境は別の仮想環境を参照している
Jupyter Notebook のカーネルが別の Python を使っている
Python では、環境ごとにインストールされているパッケージが独立しているため、別の環境ではそのモジュールが存在しないことになります。
仮想環境（venv）の仕組み
Python では、プロジェクトごとに依存関係を分離するために 仮想環境（virtual environment） を使うのが一般的です。仮想環境を使うことで、他のプロジェクトに影響を与えずにパッケージを管理できます。
✅ 仮想環境の作成
Copy
Edit
python -m venv venv
これで venv/ というディレクトリができ、その中に独立した Python 環境が作られます。
✅ 仮想環境の有効化
macOS / Linux:
Copy
Edit
source venv/bin/activate
Windows:
cmd
Copy
Edit
.\venv\Scripts\activate
✅ 仮想環境内でパッケージをインストール
Copy
Edit
pip install foo
この操作は、グローバル環境 ではなく、仮想環境内の site-packages にインストールされます。
VSCode での注意点：インタプリタの選択
VSCode では、画面左下の「Python ○○」という部分をクリックして、使用する Python インタプリタを選択できます。
ここで グローバル環境 の Python が選ばれていると、仮想環境に入っているモジュールは見つかりません。逆に、仮想環境が選ばれていれば、グローバルにはないモジュールも使用可能です。
💡ヒント：コマンドパレット（Cmd/Ctrl + Shift + P）→「Python: インタプリタの選択」で現在の環境を確認・変更できます。
最後に：確認すべきポイントまとめ
モジュールが見つからないときは、以下をチェックしましょう：
どの Python インタプリタを使っているか？
→ which python / where python で確認
→ VSCode の設定を確認
どの環境にインストールされたのか？
→ pip show autogen でインストール先パスを確認
仮想環境を正しく有効化しているか？
→ source venv/bin/activate / .venv\Scripts\activate など