🔍 Pythonのモジュールが「見つからない」と言われる理由と仮想環境の仕組み

はじめに

Python でコードを書いていて、こんなエラーに遭遇したことはありませんか？

Import "foo" could not be resolved

モジュールが正しくインストールされているはずなのに、なぜか見つからない。
これは、「インタプリタの違い」と「モジュール探索パス（sys.path）の仕組み」を理解すれば納得できます。

Python でモジュールをインポートする際、次のように書きます。

import foo

このとき Python は、内部で「autogen という名前のモジュールやパッケージがどこにあるか」を探索します。この探索は、Python のモジュール探索パスである sys.path というリストに基づいて行われます。

このリストには、以下のようなパスが含まれています：

・現在の作業ディレクトリ

・標準ライブラリのディレクトリ

・site-packages（pipでインストールされたモジュールの保存場所）

・仮想環境が使われている場合は、その仮想環境内のパス

モジュールが「見つからない」と言われる原因

たとえば：

ターミナルで 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 など