MENU

VS CodeでModuleNotFoundErrorになる原因と直し方｜ターミナルでは動くときのPython環境確認

Python

ターミナルから実行すると正常に動くのに、Visual Studio Code（VS Code）の実行ボタンやデバッグでは ModuleNotFoundError が出る。この場合、まず疑うべきなのはPythonライブラリそのものではなく、実行に使っているPython環境の違いです。

同じ「Python 3.12」「Python 3.13」と表示されていても、システムPython、venv、Condaなどで実体のパスが違えば、それぞれ別の環境です。ターミナル側には目的のパッケージが入っていても、VS Codeが別のPythonを使っていれば、そのパッケージは見つかりません。

最初に確認するのは、VS Codeの Python: Select Interpreter で選択されている環境です。そのうえで、ターミナルとVS Codeから実際に使われている python のパスを比較します。デバッグだけ失敗する場合は、さらに launch.json の python 設定を確認します。VS Code公式ドキュメントでも、選択した環境は通常の実行・デバッグ・IntelliSenseなどに利用され、デバッグについては launch.json で別のインタープリターを指定できるとされています。

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

VS Codeで入れたはずのPythonライブラリを使えないときの環境確認

ModuleNotFoundError が出たとき、すぐに pip install をやり直すのではなく、まず「どのPythonで実行しているか」を確認すると原因を切り分けやすくなります。

代表的な症状と確認場所は次のとおりです。

症状主に確認する場所
ターミナルでは動くがVS Codeの実行では失敗するPython: Select Interpreter
選びたいvenvやConda環境が一覧にない環境の保存場所、検索パス、環境検出
実行ボタンだけ別の結果になる実際の sys.executable
F5デバッグだけ失敗する.vscode/launch.json
Notebookだけ失敗するJupyterのカーネル
WSL、SSH、Dev Containerだけ失敗するリモート側のPython環境

特に重要なのは、Pythonのバージョン番号ではなくPython実行ファイルのフルパスを見ることです。

まずPython: Select Interpreterで使用環境を確認する

VS CodeでPythonファイルを開いた状態で、ステータスバーに表示されるPython環境を確認します。

環境を変更する場合は、ステータスバーのPython環境をクリックするか、コマンドパレットを開いて次のコマンドを実行します。

Python: Select Interpreter

Windowsでは Ctrl + Shift + P、macOSでは Cmd + Shift + P でコマンドパレットを開けます。

一覧から、プロジェクトで実際に使用したいvenv、Conda環境、システムPythonなどを選択します。

VS Codeの公式ドキュメントでは、選択した環境はPythonコードの実行だけでなく、デバッグやIntelliSenseなどの言語機能にも利用されます。

例えばプロジェクト内に次の仮想環境を作っているなら、

my-project/
├─ .venv/
└─ main.py

基本的には、その .venv 内のPythonを選択します。

Windowsなら概念的には次のような場所です。

my-project\.venv\Scripts\python.exe

macOSやLinuxなら次のような構成になります。

my-project/.venv/bin/python

環境を変更したら、必要に応じてVS Codeのターミナルも新しく開き直して確認すると、以前の仮想環境が残ったターミナルとの混同を避けやすくなります。

「Python 3.12」と表示されていても同じ環境とは限らない

よくある間違いが、Pythonのバージョンだけを見て同じ環境だと判断することです。

例えば次の2つは、どちらもPython 3.12だったとしても別のPython環境です。

C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe
C:\work\sample\.venv\Scripts\python.exe

.venv に requests をインストールしていても、VS Codeが上側のシステムPythonを使用していれば、

import requests

の実行時に ModuleNotFoundError になる可能性があります。

そのため、バージョン番号ではなく実行ファイルの場所まで比較することが重要です。

ターミナルとVS Codeが使うPythonのパスを比較する

環境を選択しても原因が分からない場合は、実際に使われているPythonのパスを確認します。

ターミナル側のPythonを確認する

正常に動いているターミナルで、次のコマンドを実行します。

python -c "import sys; print(sys.executable)"

ここで表示されたパスを控えます。

さらに、問題になっているパッケージがそのPython環境に入っているか確認できます。

例えば requests の場合は次のようにします。

python -m pip show requests

ここで pip show ではなく、

python -m pip

という形を使うのがポイントです。

python -m pip なら、現在確認している python と同じインタープリターに対応するpipを呼び出せます。

VS Code側のPythonを確認する

次に、VS Codeで問題が起きている実行方法を使って、次の確認用コードを実行します。

import sys

print(sys.executable)

これは確認用のコード例です。

ここで表示されるパスと、先ほどターミナルで確認したパスを比較します。

例えば、

ターミナル
C:\work\sample\.venv\Scripts\python.exe

に対して、

VS Code
C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe

となっていれば、原因はほぼ明確です。

ターミナルでは .venv を使用しているのに、VS Code側はシステムPythonを使用しています。

この場合、ライブラリを全部入れ直す必要はありません。VS Codeの Python: Select Interpreter から、

C:\work\sample\.venv\Scripts\python.exe

に対応する環境を選択すればよいことになります。

Python環境が一覧に出てこない場合

目的の仮想環境が Python: Select Interpreter の一覧に表示されない場合は、環境そのものではなく、VS Codeがその環境を検出できていない可能性があります。

現在のVS Code公式ドキュメントでは、Python環境はワークスペース内や既知の保存場所などから自動検出されます。また、追加の検索場所を設定するための python-envs.workspaceSearchPaths と python-envs.globalSearchPaths が用意されています。

まず環境が実際に存在するか確認する

例えば .venv を使用しているなら、プロジェクト内に本当に環境が存在するか確認します。

sample/
├─ .venv/
│  ├─ Scripts/
│  └─ ...
└─ main.py

仮想環境を別の場所に作成している場合は、その保存場所も確認します。

環境検出を更新する

環境を新しく作成した直後など、VS Codeの一覧に反映されていない場合は、コマンドパレットから環境検出を更新できます。

Python Environments: Refresh All Environment Managers

Python Environmentsの画面に表示される更新操作から再スキャンする方法も公式ドキュメントで案内されています。

標準以外の場所に環境を置いている場合

ワークスペース内の環境については python-envs.workspaceSearchPaths、ワークスペース外の共有環境などについては python-envs.globalSearchPaths が環境検索に使われます。

workspaceSearchPaths はワークスペースまたはフォルダー単位、globalSearchPaths はユーザー単位で設定されます。また、グローバル検索パスには絶対パスを指定する仕様になっています。

単に一覧にないという理由だけでシステムPythonへパッケージを再インストールするのではなく、まず目的の環境をVS Codeに認識させる方向で確認した方が、環境を整理した状態を維持できます。

実行は成功するのにデバッグだけModuleNotFoundErrorになる場合

通常実行では動くのに、F5キーなどでデバッグすると ModuleNotFoundError になる場合は、.vscode/launch.json を確認します。

通常、PythonデバッガーはVS Codeで選択されているPython環境を使用します。しかし、デバッグ構成の launch.json に python が指定されている場合、デバッグではそのインタープリターを使用できます。

例えば launch.json に次のような指定があるケースです。

{
  "python": "/path/to/python"
}

このパスが現在使いたい仮想環境と違っていれば、

  • 通常実行では成功する
  • デバッグでは失敗する

という状態が発生し得ます。

Windowsなら、古い仮想環境へのパスが残っていないかも確認します。

{
  "python": "C:\\old-project\\.venv\\Scripts\\python.exe"
}

デバッグ専用のPythonを意図的に使っているのでなければ、python の指定が本当に必要か確認してください。

「Python: Select Interpreterでは正しい環境を選んだのに、F5だけ動かない」という場合は、特に確認価値の高いポイントです。

正しい環境にパッケージを入れる方法

パスを比較した結果、VS Code側で選択している環境を今後使いたいのであれば、その環境へ必要なパッケージをインストールします。

例えば新しいターミナルを開き、目的の環境が有効になっていることを確認したうえで、

python -m pip install requests

のように実行します。

一方、すでにパッケージが揃っているターミナル側の仮想環境を使いたいのであれば、新たにインストールするのではなく、VS Codeのインタープリターをその環境へ変更する方が適切です。

判断基準はシンプルです。

状況対応
ターミナル側の環境が正しいVS Codeで同じ環境を選択する
VS Code側の環境を今後使いたいその環境へ必要なパッケージを入れる
デバッグだけ別環境になるlaunch.json を確認する
目的の環境が一覧にない環境検出や検索パスを確認する

全パッケージをシステムPythonへ入れ直す方法は避ける

ModuleNotFoundError が出ると、

pip install パッケージ名

を何度も実行してしまいがちです。

しかし環境の食い違いが原因なら、別のPythonへ同じパッケージを追加しているだけになる場合があります。

例えば、

システムPython
Python312/

と、

プロジェクト用
project/.venv/

の両方に同じライブラリを入れてしまうと、一時的にエラーが消えても「どのプロジェクトがどの環境を使っているのか」が分かりにくくなります。

先に、

python -c "import sys; print(sys.executable)"

でPythonの場所を確認し、その後で必要なら、

python -m pip install パッケージ名

とする方が原因を整理しやすくなります。

Pythonのパスが同じなのにModuleNotFoundErrorになる場合

ターミナルとVS Codeで sys.executable が完全に一致しているなら、次は環境以外の原因を確認します。

まず対象パッケージが本当にその環境へインストールされているか確認します。

python -m pip show パッケージ名

一覧から調べたい場合は、

python -m pip list

でも確認できます。

それでも解決しない場合は、次のような可能性があります。

  • インストール時のパッケージ名と import 名が異なる
  • 自作モジュールを読み込もうとしている
  • 実行時のカレントディレクトリが想定と違う
  • PYTHONPATH などモジュール検索パスに関する設定が影響している
  • 同名のファイルやフォルダーがプロジェクト内に存在する

ここまで来ると「VS Codeが別のPythonを使っている」という問題とは分けて調査した方が分かりやすくなります。

複数フォルダーを開いている場合は設定範囲にも注意する

複数のPythonプロジェクトを1つのワークスペースで扱っている場合、「一度インタープリターを選べばすべて同じ」とは限りません。

現在のVS CodeのPython環境機能では、ファイルやフォルダーをPython Projectとして扱い、それぞれに環境を割り当てる仕組みがあります。実行やデバッグでは、そのプロジェクトに割り当てられた環境が利用されます。

例えば、

workspace/
├─ backend/
│  └─ .venv/
└─ tools/
   └─ .venv/

のような構成では、backend と tools が別々の環境を使っていても不自然ではありません。

「昨日まで別のフォルダーでは動いていた」という事実だけでは、現在開いているファイルも同じPython環境だとは判断できない点に注意してください。

WSL・SSH・Dev Containerではローカル環境と分けて考える

WSL、SSH接続、Dev ContainerなどでVS Codeを使用している場合は、ローカルPCのPythonとリモート側のPythonを混同しないことも重要です。

例えばWindows側に、

C:\work\.venv\Scripts\python.exe

があっても、WSL内で実行するPythonとは別物です。

リモート環境で実行しているなら、パッケージも基本的にはその実行環境側で確認します。

「WindowsのPowerShellではimportできるのに、WSLで開いたVS Codeではできない」といった場合は、単純なインタープリター選択だけでなく、どのOS・コンテナ・リモートホスト上でPythonが動いているかまで確認してください。

Jupyter NotebookはPythonファイルの実行と分けて確認する

.py ファイルでは正常なのに .ipynb だけ ModuleNotFoundError になる場合は、通常のPythonインタープリター選択だけでなくNotebookのカーネルを確認します。

現在のVS Code公式ドキュメントでは、Jupyter Notebookの環境検出はPython Environments APIとは別の仕組みを使用しており、Environment Managersに表示される環境とNotebookのカーネル候補が一致しない場合があると説明されています。

したがって、

Python: Select Interpreter

で正しい環境を選んだことだけを根拠に、Notebookも同じ環境で動いていると判断しない方が安全です。

Notebookでは、画面上で選択されているカーネルも個別に確認してください。

最短で原因を特定するなら4項目を順番に確認する

ターミナルでは動くのにVS Codeで ModuleNotFoundError になる場合は、次の順番で確認すると効率的です。

  1. Python: Select Interpreterで目的の環境が選ばれているか確認する
  2. ターミナルとVS Codeの sys.executable を比較する
  3. 環境が一覧にないなら検索場所と環境検出を確認する
  4. デバッグだけ失敗するなら launch.json の python を確認する

特に重要なのは、「Python 3.12だから同じ」と判断せず、Python実行ファイルのフルパスを比較することです。

パスが違えば、まず環境をそろえます。パスが一致しているなら、その時点でパッケージのインストール状態やモジュール検索パスの問題へ進めばよく、無関係なPython環境へパッケージを何度もインストールする必要はありません。

ModuleNotFoundError を見たら、最初の一手を pip install ではなく、

python -c "import sys; print(sys.executable)"

にするだけでも、原因をかなり絞り込みやすくなります。

Python
Python venv Visual Studio Code ModuleNotFoundError

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次