PythonのModuleNotFoundErrorとは？原因と直し方を初心者向けに解説

Pythonのコードを実行したとき、次のようなエラーが表示されることがあります。

ModuleNotFoundError: No module named 'requests'

「ModuleNotFoundError」は、読み込もうとしたモジュールをPythonが見つけられないときに発生するエラーです。

ライブラリがインストールされていない場合だけでなく、モジュール名の間違いや実行環境の違いが原因になることもあります。

この記事では、ModuleNotFoundErrorが発生する主な原因と直し方を、初心者向けに順番に解説します。

ModuleNotFoundErrorとは

Pythonでは、「import」を使って外部の機能を読み込めます。

例えば、HTTP通信に使われる「requests」を読み込む場合は、次のように書きます。

# requestsを読み込む
import requests

# Webページの情報を取得
response = requests.get("https://example.com")

print(response.status_code)

Pythonが「requests」を見つけられない場合は、次のエラーが発生します。

ModuleNotFoundError: No module named 'requests'

「No module named ‘requests’」は、「requestsという名前のモジュールがありません」という意味です。

エラーメッセージの最後に表示されている名前を確認すると、どのモジュールが見つからないのか分かります。

ライブラリがインストールされていない

ModuleNotFoundErrorの代表的な原因は、必要なライブラリがインストールされていないことです。

Pythonには、最初から使える標準ライブラリと、あとから追加する外部ライブラリがあります。

「requests」は外部ライブラリなので、使用する前にインストールが必要です。

Windowsでは、ターミナルやコマンドプロンプトで次のコマンドを実行します。

py -m pip install requests

環境によっては、次のコマンドを使います。

python -m pip install requests

macOSやLinuxでは、次のコマンドを使う場合もあります。

python3 -m pip install requests

インストールが完了したら、もう一度Pythonのコードを実行します。

「pip install requests」をPythonのプログラム内へ書くのではなく、ターミナルで実行する点に注意しましょう。

インストールできたか確認する

ライブラリがインストールされているかは、次のコマンドで確認できます。

python -m pip show requests

Windowsで「py」を使っている場合は、次のように実行します。

py -m pip show requests

インストールされていれば、ライブラリ名やバージョン、保存場所などが表示されます。

一覧から確認する方法もあります。

python -m pip list

「pip list」にはインストール済みのライブラリが表示されます。

ただし、一覧に名前があっても、コードを実行するPythonとは別の環境にインストールされている場合があります。

pipとPythonの参照先が異なっている

ライブラリをインストールしたのにModuleNotFoundErrorが直らない場合は、「pip」と「Python」が別の環境を参照している可能性があります。

パソコンに複数のPythonが入っていると、次のような状態になることがあります。

Python Aで使われるpip → requestsをインストール
Python Bでコードを実行 → requestsが見つからない

この問題を避けるために、「pip install」だけでなく、次の形式でインストールするのがおすすめです。

python -m pip install requests

「python -m pip」と書くと、そのPythonに対応するpipを使ってインストールできます。

Windowsで「py」を使ってコードを実行している場合は、次の形式を使います。

py -m pip install requests

重要なのは、「インストールに使うPython」と「コードを実行するPython」をそろえることです。

使用しているPythonの場所を確認する

コードを実行しているPythonの場所は、次のプログラムで確認できます。

import sys

# 現在使っているPythonの場所を表示
print(sys.executable)

インストール先も確認してみましょう。

python -m pip show requests

「Location」に表示された場所が、現在のPython環境と大きく異なる場合は、別の環境へインストールしている可能性があります。

「インストールしたか」だけでなく、「どのPythonへインストールしたか」を確認することが解決のポイントです。

モジュール名のスペルが間違っている

「import」に書いた名前が間違っている場合も、ModuleNotFoundErrorが発生します。

# requestsのスペルが間違っている
import reqests

正しくは次のとおりです。

# 正しいモジュール名
import requests

次の点を確認しましょう。

Pythonでは、大文字と小文字が区別されます。

サンプルコードを手入力した場合は、ライブラリ名をコピーして比較すると間違いを見つけやすくなります。

インストール名とimport名が違う場合

ライブラリによっては、インストール時の名前と「import」に書く名前が異なります。

代表的な例が、画像処理ライブラリの「Pillow」です。

インストールするときは、次の名前を使います。

python -m pip install Pillow

コードで読み込むときは、「Pillow」ではなく「PIL」と書きます。

# PillowはPILという名前で読み込む
from PIL import Image

print("画像処理の準備ができました")

インストール名をそのまま「import」へ書けばよいとは限りません。

公式ドキュメントや利用している教材を確認し、「インストールするときの名前」と「読み込むときの名前」を分けて考えましょう。

仮想環境が有効になっていない

Pythonでは、プロジェクトごとにライブラリを分けて管理するために「仮想環境」を使うことがあります。

仮想環境の中へライブラリをインストールしても、別の環境でコードを実行すると、そのライブラリは見つかりません。

仮想環境を作成する基本的なコマンドは次のとおりです。

python -m venv .venv

Windowsで仮想環境を有効にする場合は、次のコマンドを使います。

.venv\Scripts\activate

macOSやLinuxでは、次のように実行します。

source .venv/bin/activate

仮想環境を有効にした後で、必要なライブラリをインストールします。

python -m pip install requests

ターミナルの先頭に「(.venv)」などと表示されていれば、仮想環境が有効になっている目安になります。

コードエディターを再起動した場合や、新しいターミナルを開いた場合は、仮想環境を再び有効にする必要があることもあります。

Visual Studio Codeで別のPythonが選ばれている

Visual Studio Codeでは、コードを実行するPythonを選択できます。

ターミナルでライブラリをインストールしても、Visual Studio Codeが別のPythonを使用していれば、ModuleNotFoundErrorが発生します。

次の点を確認しましょう。

仮想環境を使用している場合は、「.venv」と表示されたPythonを選びます。

Jupyter Notebookを使っている場合は、右上などに表示されるカーネルも確認してください。

「ターミナルのPython」「エディターのPython」「Notebookのカーネル」は、別々の環境になっている可能性があります。

自作モジュールが見つからない

自分で作ったPythonファイルを読み込む場合にも、ModuleNotFoundErrorが発生することがあります。

次のようなファイル構成を考えてみましょう。

project/
├── main.py
└── calculator.py

「calculator.py」の内容は次のとおりです。

def add(a, b):
    # 2つの数値を合計
    return a + b

同じフォルダにある「main.py」からは、次のように読み込めます。

# calculator.pyからadd関数を読み込む
from calculator import add

result = add(10, 20)

print(result)  # 30

「calculator.py」が別のフォルダにある場合や、ファイル名が間違っている場合は読み込めません。

次の点を確認しましょう。

初心者のうちは、関連するPythonファイルを同じプロジェクトフォルダへ置くと、構成を把握しやすくなります。

フォルダを読み込めない場合

複数のPythonファイルをフォルダにまとめている場合は、読み込み方がファイル構成と合っているか確認します。

project/
├── main.py
└── tools/
    ├── __init__.py
    └── calculator.py

この場合、「main.py」から次のように読み込めます。

# toolsフォルダ内のcalculator.pyを読み込む
from tools.calculator import add

result = add(10, 20)

print(result)  # 30

「tools」や「calculator」のスペルが実際のフォルダ名、ファイル名と一致している必要があります。

プロジェクトの途中のフォルダからファイルを直接実行すると、読み込みの基準になる場所が変わることもあります。

複雑な構成では、「どのファイルがある場所から実行しているか」も確認しましょう。

ファイル名がライブラリ名と重複している

自分で作ったファイルの名前が、読み込みたいライブラリと同じになっていると、予期しない問題が起こることがあります。

例えば、「requests.py」という自作ファイルを作成すると、本来の「requests」ではなく、自作ファイルが優先して読み込まれる場合があります。

project/
├── main.py
└── requests.py

自作ファイルには、既存のライブラリと重複しにくい名前を付けましょう。

名前を変更した後も問題が続く場合は、同じフォルダに作成されたキャッシュ用の「pycache」が影響していないか確認します。

ただし、原因を確認せずにフォルダを削除する必要はありません。まずは、自作ファイル名と「import」の名前が重なっていないかを見るのが先です。

標準ライブラリはpipでインストールしない

Pythonに最初から含まれている標準ライブラリは、通常「pip」でインストールする必要がありません。

例えば、次のようなモジュールです。

# Pythonに最初から含まれている標準ライブラリ
import os
import sys
import json
import datetime

print("標準ライブラリを読み込みました")

標準ライブラリでModuleNotFoundErrorが発生した場合は、インストール不足よりも次の原因を確認します。

エラーを見たら何でも「pip install」するのではなく、「外部ライブラリなのか、標準ライブラリなのか」を確認することが大切です。

requirements.txtからまとめてインストールする

他の人が作ったプロジェクトを動かす場合は、「requirements.txt」というファイルが用意されていることがあります。

このファイルには、プロジェクトで必要なライブラリが記録されています。

requests==2.32.3
pandas==2.2.3
Flask==3.1.0

必要なライブラリは、次のコマンドでまとめてインストールできます。

python -m pip install -r requirements.txt

ライブラリを一つずつ推測してインストールする前に、プロジェクト内に「requirements.txt」や設定ファイルがないか確認しましょう。

インストール時に権限エラーが出る場合

ライブラリのインストール時に権限に関するエラーが出た場合でも、すぐに管理者権限で実行する必要はありません。

仮想環境を作成し、その中へインストールする方法が安全で管理しやすいでしょう。

python -m venv .venv

仮想環境を有効にしてからインストールします。

python -m pip install requests

仮想環境を使うと、パソコン全体のPython環境を変更せず、プロジェクトに必要なライブラリだけを管理できます。

ModuleNotFoundErrorを直す順番

ModuleNotFoundErrorが発生したときは、手当たり次第に設定を変更せず、次の順番で確認すると原因を見つけやすくなります。

特に重要なのは、「ライブラリが存在しない」のか、「別の場所に存在していて今のPythonから見えない」のかを分けることです。

ModuleNotFoundErrorは、本棚に本がない状態だけでなく、「本は別の部屋にあるが、今いる部屋から見つけられない状態」でも発生します。

この違いを意識すると、同じライブラリを何度もインストールする前に、Pythonの参照先を確認できるようになります。

まとめ

「ModuleNotFoundError」は、Pythonが指定されたモジュールを見つけられないときに発生するエラーです。

代表的なメッセージは次のとおりです。

ModuleNotFoundError: No module named 'requests'

外部ライブラリが未インストールの場合は、次のようにインストールします。

python -m pip install requests

インストールしても直らない場合は、次の点を確認しましょう。

ModuleNotFoundErrorを見たときに、必ずしも「インストールに失敗した」とは限りません。

「Pythonは今、どの環境からモジュールを探しているのか」という視点を持つと、原因を見つけやすくなります。

まずはエラーメッセージのモジュール名を確認し、スペル、インストール状況、実行環境の順番で調べてみましょう。