Python ImportError・ModuleNotFoundErrorの解決法
Pythonでimport文を使ったときに発生するImportErrorやModuleNotFoundErrorは、初心者が頻繁に遭遇するエラーです。「モジュールが見つからない」と言われても、何をどうすればいいかわからないことが多いでしょう。この記事では主な原因と解決方法を解説します。
ImportError・ModuleNotFoundErrorとは
この2つのエラーは、Pythonが指定されたモジュール（ライブラリ）を見つけられないときに発生します。
import requests
# ModuleNotFoundError: No module named 'requests'
from mymodule import helper
# ModuleNotFoundError: No module named 'mymodule'ModuleNotFoundErrorはPython 3.6以降で導入されたImportErrorのサブクラスです。基本的な対処法は同じです。
パターン1: ライブラリがインストールされていない
最も多い原因です。外部ライブラリは自分でインストールする必要があります。
# エラーの例
# ModuleNotFoundError: No module named 'requests'解決方法: pipでインストール
# ライブラリをインストール
pip install requests
# バージョンを指定してインストール
pip install requests==2.31.0
# インストール済みのライブラリを確認
pip list
# 特定のライブラリがインストールされているか確認
pip show requestsライブラリ名がわからないときは、PyPI（https://pypi.org/）で検索できます。
よくある間違い: pip と pip3
# Pythonのバージョンが複数ある環境では注意
python --version # Python 3.x を確認
pip --version # どのPythonに紐づいているか確認
# Python 3 用のpipを明示的に使う
pip3 install requests
# または
python3 -m pip install requestspythonコマンドで起動するPythonとpipが紐づいているPythonのバージョンが異なることがあります。python -m pip installの形式を使えば確実です。
パターン2: 仮想環境の問題
仮想環境を使っている場合、その環境が有効化されていないとライブラリが見つかりません。
# 仮想環境を有効化していない状態で実行するとエラーになる
python main.py
# ModuleNotFoundError: No module named 'flask'解決方法: 仮想環境を有効化する
# 仮想環境の有効化
# macOS / Linux
source venv/bin/activate
# Windows
venv\Scripts\activate
# 有効化後にライブラリをインストール
pip install flask
# 仮想環境が有効かどうか確認する方法
which python
# /path/to/project/venv/bin/python と表示されればOKVS Codeを使っている場合は、右下のPythonバージョン表示をクリックして仮想環境のインタプリタを選択しましょう。
パターン3: 自作モジュールのimportエラー
自分で作ったファイルをimportするときにもエラーが起きることがあります。
プロジェクト/
main.py
utils/
helper.py# main.py
from utils.helper import my_function
# ModuleNotFoundError: No module named 'utils'解決方法: 実行ディレクトリとパスを確認
# main.pyがあるディレクトリで実行する
cd プロジェクト
python main.py# 現在のPythonパスを確認する
import sys
print(sys.path)Pythonはsys.pathに含まれるディレクトリからモジュールを探します。実行するディレクトリが想定と違うと見つかりません。
init.pyの有無
Python 3.3以降では__init__.pyがなくてもパッケージとして認識されますが、明示的に置いておくと安全です。
プロジェクト/
main.py
utils/
__init__.py # 空ファイルでOK
helper.pyパターン4: ファイル名の衝突
自分のファイル名が標準ライブラリやインストール済みライブラリと同じ名前だと、自分のファイルが優先されてエラーになります。
# random.py というファイルを作ってしまった場合
import random
print(random.randint(1, 10))
# AttributeError: module 'random' has no attribute 'randint'
# （自分のrandom.pyが読み込まれてしまう）解決方法: ファイル名を変更する
# NG: 標準ライブラリと同じ名前
random.py
email.py
json.py
test.py
# OK: 別の名前にする
my_random.py
email_sender.py
json_parser.py
test_app.py避けるべきファイル名の目安として、importで使えるライブラリ名と同じファイル名は避けましょう。
パターン5: 相対importと絶対importの混同
myapp/
__init__.py
main.py
models/
__init__.py
user.py
services/
__init__.py
auth.py# services/auth.py から models/user.py をimportしたい
# NG: スクリプトとして直接実行すると相対importはエラー
from ..models.user import User
# ImportError: attempted relative import with no known parent package
# OK: 絶対importを使う
from myapp.models.user import User
# プロジェクトルートから実行する
# python -m myapp.services.auth相対import（..や.を使う）はパッケージ内でのみ有効です。ファイルを直接python auth.pyで実行すると動きません。
トラブルシューティングの手順
ImportErrorに遭遇したら、以下の手順で原因を切り分けましょう。
# 1. Pythonのバージョンとパスを確認
import sys
print(sys.version)
print(sys.executable)
# 2. モジュール検索パスを確認
print(sys.path)
# 3. インストール済みパッケージを確認
# ターミナルで: pip list | grep パッケージ名
# 4. モジュールの場所を確認
import requests # インストール済みの場合
print(requests.__file__)まとめると、ImportError対処の基本は「正しいPython環境で」「正しいライブラリがインストールされていて」「正しいパスから実行する」の3点です。エラーが出たら、まずこの3つを順番に確認してみてください。