Python ModuleNotFoundError: No module named ‘…’ の原因と解決方法【よくある落とし穴と実践的な対処法】

ModuleNotFoundError: No module named ‘…’ (例: ‘requests’) とは

Python開発中に遭遇する「ModuleNotFoundError」は、多くのエンジニアが一度は経験するエラーでしょう。特にプロジェクトが複雑になったり、仮想環境を使い始めたりすると遭遇しやすくなります。このエラーは、Pythonインタープリタが必要なモジュールを見つけられないときに発生します。

エラーの発生パターン

このエラーは主に以下のようなケースで発生します。

パターン1: パターン1: モジュール名の間違いやタイポ

import reqests # 'requests' のタイポ

def fetch_data():
    response = reqests.get('https://api.example.com/data')
    print(response.json())

このエラーは、インポートしようとしているモジュール名が間違っているか、単なるタイポである場合に発生します。Pythonは、指定された名前のモジュールを見つけられないため、ModuleNotFoundErrorを発生させます。特に、頻繁に使うライブラリでも意外なミスがあるものです。

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

def fetch_data():
    response = requests.get('https://api.example.com/data')
    print(response.json())

パターン2: パターン2: 仮想環境の有効化忘れ、またはパッケージのインストール忘れ

# 仮想環境がアクティブになっていない状態で実行
# pip install requests を実行したが、仮想環境外のシステムPythonにインストールされている

import requests

def main():
    print(f"Requests library version: {requests.__version__}")

if __name__ == '__main__':
    main()

Pythonプロジェクトでは、依存関係の分離のために仮想環境（Virtual Environment）を使用するのが一般的です。仮想環境を有効化せずにスクリプトを実行したり、必要なパッケージを仮想環境内にインストールし忘れたりすると、ModuleNotFoundErrorが発生します。システム全体のPythonにはインストールされていても、現在の仮想環境には存在しないためです。

# 仮想環境を有効化する (例: source venv/bin/activate)
# 仮想環境内でパッケージをインストールする (例: pip install requests)

import requests

def main():
    print(f"Requests library version: {requests.__version__}")

if __name__ == '__main__':
    main()

パターン3: パターン3: カスタムモジュールのパスが通っていない

# project_root/main.py
# from my_module import some_function # 間違い

# project_root/utils/my_module.py
# def some_function():
#     print('Hello from my_module')

# main.py の内容
from utils.my_module import some_function # main.py から相対パスで指定

some_function()

自分で作成したカスタムモジュールやパッケージをインポートする際、Pythonインタープリタがそのモジュールを見つけられない場合があります。これは主に、スクリプトの実行場所とモジュールが配置されているディレクトリの関係、またはPythonのモジュール検索パス（sys.path）に、モジュールが含まれるディレクトリが追加されていない場合に起こります。

# project_root/main.py
# from utils.my_module import some_function # 正しい相対パス指定

# project_root/utils/my_module.py
# def some_function():
#     print('Hello from my_module')

# main.py の内容
# 実行は project_root ディレクトリで行うか、
# Pythonパスに project_root を追加する
# 例: python -m utils.my_module は通常はサブパッケージから直接実行されない
# もしくは、プロジェクトのルートディレクトリを sys.path に追加する (一時的なデバッグ用途)

# 正しいプロジェクト構造と実行例
# my_project/
# ├── main.py
# └── utils/
#     └── __init__.py # パッケージとして認識させるために必要
#     └── my_module.py

# main.py の内容
from utils.my_module import some_function

some_function()

# 実行は my_project ディレクトリから `python main.py`
# (__init__.py が存在しないと、Python 3.3以降でもパッケージとして扱われずエラーになる可能性あり)

根本原因の特定方法

ModuleNotFoundErrorが発生した場合、まずはエラーメッセージに示されているモジュール名が正しいか、タイポがないかを確認します。次に、現在のPython環境でpip listを実行し、目的のパッケージがインストールされているかをチェックします。さらに、import sys; print(sys.path)を実行して、Pythonがモジュールを探すパスに、目的のモジュールが存在するディレクトリが含まれているかを確認すると、原因の特定に役立ちます。

import sys
import os

# 現在のPython環境のパスを確認
print("Python Path (sys.path):")
for p in sys.path:
    print(f"  - {p}")

# 特定のモジュールがインストールされているか確認 (例: requests)
# try:
#     import requests
#     print(f"\nrequests is installed: {requests.__version__}")
# except ModuleNotFoundError:
#     print("\nrequests is NOT installed.")

# 仮想環境がアクティブか確認 (非公式な方法ですが、目安になります)
print(f"\nVirtual environment active: {'VIRTUAL_ENV' in os.environ}")
if 'VIRTUAL_ENV' in os.environ:
    print(f"VIRTUAL_ENV: {os.environ['VIRTUAL_ENV']}")

防止策とベストプラクティス

このエラーを未然に防ぐためには、常に{marker}仮想環境を使用し、プロジェクトごとに依存関係を管理する{/marker}ことが重要です。requirements.txtファイルを作成し、pip install -r requirements.txtで依存パッケージをインストールする習慣をつけましょう。また、カスタムモジュールを配置する際は、Pythonのパッケージングルールに従い、__init__.pyファイルを適切に配置し、インポートパスを明確にすることが肝要です。

# プロジェクトルートに requirements.txt を作成
# 例:
# requests==2.28.1
# Django==4.1.3

# 仮想環境を作成し、アクティブ化
# python -m venv venv
# source venv/bin/activate # Linux/macOS
# .\venv\Scripts\activate # Windows PowerShell

# 依存関係を一括インストール
pip install -r requirements.txt

よくある質問（FAQ）

この用語と一緒に知っておきたい用語

このエラーと一緒にしっておきたいエラー