Last Updated on 2025年7月28日
概要
Pythonでスクリプトを実行していると、時折遭遇するエラーが ModuleNotFoundError: No module named 'xxx' です。このエラーは、「指定されたモジュールが見つからない」という内容で、初心者から上級者まで多くの開発者が一度は直面します。本記事では、このエラーの詳細と、その原因、対処法について詳しく解説します。
目次
エラー内容
Pythonで次のようなコードを実行したとします：
|
1 2 |
import xxx |
このとき、下記のようなエラーメッセージが表示されることがあります。
|
1 2 3 4 5 |
Traceback (most recent call last): File "main.py", line 1, in <module> import xxx ModuleNotFoundError: No module named 'xxx' |
このエラーは、Pythonが「xxx」という名前のモジュールを探したが、見つからなかったことを意味します。
原因
このエラーが発生する主な原因は以下の通りです。
- モジュールがインストールされていない
pipでインストールする必要がある外部ライブラリがインストールされていない。 - インストールしたが環境が違う
仮想環境内にインストールしたのに、グローバル環境で実行している、などのケース。 - タイポ（綴り間違い）
例：import numpyyのようにスペルミスしている。 - Pythonバージョンによる差異
一部のモジュールはPythonのバージョンによってサポートされていない場合があります。 - パスが通っていない自作モジュール
自分で作成したモジュールの場所がsys.pathに含まれていない。
対処法
原因に応じた対処方法を解説します。
1. モジュールをインストールする
まず、必要なモジュールがインストールされていない場合は、pipでインストールします。
|
1 |
pip install xxx |
Python3環境では以下のように指定することもあります。
|
1 |
pip3 install xxx |
2. 仮想環境を確認する
仮想環境を使っている場合、その環境にモジュールがインストールされているか確認してください。
|
1 2 |
which python pip list |
仮想環境に入ってからインストールすることを忘れずに。
3. スペルミスを修正する
単純なミスですが意外と多いです。綴りが正しいかどうかを確認しましょう。
4. 自作モジュールのパスを追加する
自分で作ったモジュールが別のディレクトリにある場合、Pythonにパスを通す必要があります。
|
1 2 |
import sys sys.path.append('/path/to/your/module') |
5. Pythonバージョンに合ったモジュールを使う
モジュールによっては Python 3.10 以上でしか動作しないものもあります。バージョンを確認し、必要に応じてアップデートしましょう。
|
1 |
python --version |
補足
もしプロジェクトで複数人が開発している場合、requirements.txt を使って必要なモジュールを明示しておくと便利です。
|
1 |
pip freeze > requirements.txt |
また、Jupyter Notebookを使っている場合、以下のようにノートブック上でインストールできます。
|
1 |
!pip install xxx |
まとめ
ModuleNotFoundError: No module named 'xxx' は非常によく見かけるエラーでありながら、原因や状況によっては対処に手間取ることもあります。基本的には以下の点をチェックすれば解決することが多いです。
- モジュールのインストールを確認
- 仮想環境の有無を確認
- 綴りを確認
- Pythonのバージョンや環境の整合性を確認
- 必要ならパスを通す
このエラーに慣れると、Python開発の効率がぐっと上がります。今後もエラーと向き合いながら、スムーズな開発を心がけていきましょう。
