PythonでModuleNotFoundErrorが出る原因と結論
Pythonでの開発プロセスにおいて、多くのエンジニアが一度は遭遇するのが「ModuleNotFoundError: No module named ‘モジュール名’」というエラーです。このエラーは、Pythonスクリプトを実行した際に、コード内でインポート（import）しようとした外部ライブラリやパッケージを、Pythonインタプリタが見つけられなかったことを意味します。
「さきほど確かに pip install でパッケージをインストールしたはずなのに、なぜかエラーが解消されない」と頭を抱えるケースは非常に多いです。その根本的な原因のほとんどは、「パッケージをインストールしたPython環境」と「実際にスクリプトを実行しているPython環境」が一致していないことにあります。特に、プロジェクトごとに個別のライブラリ依存関係を保持する「仮想環境（venv）」が正しく有効化（アクティベート）されていない状態でプログラムを実行してしまうと、システムグローバルのPython環境や別の環境を参照してしまい、このエラーが発生します。
結論として、現在実行しているPythonコマンドがPC内のどの場所（パス）を参照しているかを特定し、正しい仮想環境（venv）をアクティベートした上で、必要なライブラリをその環境内にインストールし直すことで、このエラーは確実かつ迅速に解決することができます。
venvの適用状態を確認する3つの手順
仮想環境が正しく構築され、実行環境としてアクティブになっているかを確認するための詳細な3ステップの手順を解説します。OSごとの挙動の違いに注意しながら、ターミナルで一つずつコマンドを実行していきましょう。
1. Pythonの実行パスを確認する
現在ターミナルが認識している「python」コマンドの実体が、どのディレクトリに存在するプログラムなのかを確認します。これにより、グローバル環境のPythonを呼び出しているのか、それともプロジェクト固有の仮想環境内のPythonを呼び出しているのかが判別できます。
ターミナルまたはコマンドプロンプトを開き、使用しているOSに合わせて以下のコマンドを実行してください。
・Windows (PowerShell): Get-Command python
・Windows (コマンドプロンプト): where python
・Mac / Linux: which python（または which python3）
【確認のポイント】
出力されたパスの途中に、プロジェクトフォルダー内の仮想環境ディレクトリ名（例: .venv/bin/python や .venv\Scripts\python.exe）が含まれているか確認してください。もし /usr/bin/python3 や C:\Users\Username\AppData\Local\Programs\Python\... のようなグローバルパスが表示されている場合は、仮想環境が有効になっていません。
2. 仮想環境（venv）をアクティベートする
パスが正しく仮想環境を指していない場合、またはターミナルの左端（プロンプトの先頭）に (.venv) などの仮想環境名が表示されていない場合は、明示的にアクティベート処理を実行する必要があります。
プロジェクトのルートディレクトリ（.venv フォルダが配置されている場所）に移動し、以下のコマンドを実行します。
・Windows (PowerShell): .\.venv\Scripts\Activate.ps1
※PowerShellで実行ポリシーエラーが発生する場合は、事前に Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process を実行して許可を与えてください。
・Windows (コマンドプロンプト): .\.venv\Scripts\activate.bat
・Mac / Linux: source .venv/bin/activate
アクティベートに成功すると、ターミナルの入力行の先頭に (.venv) と表示され、現在その仮想環境が有効であることが視覚的に確認できるようになります。
3. インストール済みパッケージの一覧を確認する
仮想環境をアクティベートした状態で、エラーの対象となっているライブラリが本当にその環境へインストールされているかを確認します。以下のコマンドを実行してください。
pip list
出力されたパッケージ一覧の中に、ModuleNotFoundError で指摘されたライブラリ名（例: pandas や requests）が存在するか確認します。もし存在しない場合は、以下のコマンドを使い、アクティベート状態を維持したままパッケージをインストールします。
pip install パッケージ名
（例: pip install pandas）
動作確認とトラブル時のチェックリスト
仮想環境のアクティベートやパッケージのインストールを行っても依然としてエラーが解決しない場合や、エディタとの連携で不整合が生じている場合は、以下のチェックリストを参考に現在の開発環境を再点検してください。
まとめと再発防止策
ModuleNotFoundError は一見すると複雑な不具合に見えますが、その実態はPythonの実行環境（Path）のズレによる単純な認識ミスであることがほとんどです。このエラーの再発を防ぎ、快適でポータブルな開発環境を維持するために、以下の3つのベストプラクティスを日々のワークフローに取り入れましょう。
1. プロジェクトごとに仮想環境を必ず作成する
グローバル環境に直接ライブラリをインストールし続けると、パッケージ同士の依存関係が衝突し、システム全体のPython環境が壊れてしまう原因になります。新しくプロジェクトを開始する際は、必ず python -m venv .venv を実行し、完全に独立したクリーンな開発スペースを確保する癖をつけましょう。
2. requirements.txt を用いて依存関係を一元管理する
開発に必要なライブラリをインストールした後は、以下のコマンドを実行してインストール済みのパッケージ一覧をテキストファイルに書き出しておきます。
pip freeze > requirements.txt
これにより、別のPCへの移行時や他の開発メンバーとの共同開発時に、pip install -r requirements.txt を実行するだけで、一瞬で全く同一の実行環境を安全に再現することができます。
3. .gitignore に仮想環境ディレクトリを追加する
仮想環境内のディレクトリ（.venv など）は、各OSや環境に依存したバイナリファイルが多く含まれているため、Gitなどのバージョン管理システムにコミットしてはいけません。プロジェクトのルートに .gitignore ファイルを作成し、設定行に .venv/ もしくは venv/ を追加して、リポジトリへの不要なアップロードを防止しましょう。
筆者の環境で実際に確認した結果
確認日：2026年10月14日／環境：Windows 11 Home（ビルド26300）、Windows PowerShell 5.1、Python 3.14
実際に新しいvenvを作って、グローバル環境との違いを確認しました。
> python -m venv .venv
> .venv\Scripts\python.exe -c "import sys; print(sys.prefix); print(sys.base_prefix)"
...\rin_verify\.venv
...\Programs\Python\Python314
> .venv\Scripts\python.exe -m pip list
Package Version
------- -------
pip 26.2.1
> .venv\Scripts\python.exe -c "import requests"
ModuleNotFoundError: No module named 'requests'グローバルのPython 3.14には requests が入っていますが、作ったばかりのvenvには pip しかなく、同じ import requests が失敗しました。また where python を実行すると、最初に出てきたのは ...\Microsoft\WindowsApps\python.exe（Microsoft Storeのエイリアス。ファイルサイズは0バイト）で、インストールしたPythonは2番目でした。どのpython.exeが動いているかは sys.executable と sys.prefix で確認できます。
RIN WORK LABのツール：RIN Tools｜AIエージェントの事故を減らす 個人開発テンプレ集［Claude Code編］
AIエージェントに作業を任せる前に、変更範囲・禁止事項・完了条件を整理するための指示書テンプレート集です。まずは無料サンプル（5ページPDF＋指示書サンプル）で形式を確認できます。
無料サンプルを見る（BOOTH） ／ 有料版（1,500円）
※当サイトの運営者（RIN WORK LAB）がBOOTHで販売している商品です。
