PythonのModuleNotFoundErrorって何？解決するにはどうしたらいいの？

この記事では、Pythonでよく出るエラーのひとつであるModuleNotFoundErrorを、IT初心者にもわかりやすく、かつ実践的に解説します。

疑問を投げかけながら読み進められるように構成し、具体的なサンプルコードやコマンド、よくある落とし穴とその解決策を丁寧に紹介します。さらに、あなたから提供された「エンジニア歴10年」という一次情報を反映した実務的アドバイスも含めています。

ModuleNotFoundErrorって結局何？¶

プログラムを実行したら、次のような赤いエラーが出たことはありませんか？

Traceback (most recent call last):
  File "example.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

このメッセージは、Pythonが requests という名前のモジュール（またはパッケージ）を見つけられなかったということです。 見つからない理由は複数あり、それを一つずつ潰していくのが解決の近道です。

次に、「なぜ見つからないのか？」を掘り下げていきます。

見つからない理由（根本原因を感覚でつかむ）¶

ここからは、よくある原因をイメージで説明します。「あ、これ私のケースかも」と感じるところから調べ始めましょう。

パッケージがそもそもインストールされていない¶

パッケージがそもそもインストールされていないというは、単純ですが最も多い原因です。 pip install をしていない、あるいは別のPython環境にインストールしている場合があります。

違うPython実行環境を使っている¶

次の原因は、違うPython実行環境を使っていることです。 たとえばターミナルで python と pip が別のPythonを指しているケースです。

Windowsやmac、Linuxで環境が複雑になりがちです。

PYTHONPATH や sys.path にモジュールの置き場所がない¶

次の原因は、PYTHONPATH や sys.path にモジュールの置き場所がないことです。 自作モジュールを同じディレクトリに置いていない、パッケージ構成が間違っていると見つかりません。

ファイル名やパッケージ名の衝突¶

次の原因は、ファイル名やパッケージ名の衝突です。 自分のファイル名が標準ライブラリやインストール済みパッケージと同じだと、意図せずインポートに失敗します。

ここからは具体的な手順で「原因特定 → 解決」する流れを示します。初めての人でも順を追えば解決できます。

対処方法1.エラーの読み取りを丁寧にする¶

エラーを対処するには、まずはエラーメッセージ全体を落ち着いて読むことです。 最初に示した ModuleNotFoundError: No module named 'requests' の 'requests' 部分が重要です。ここに表示されるモジュール名が調査対象になります。

次に確認するのは「どのPython」が動いているかです。ターミナルで次を実行してみましょう。

python -V
which python   # mac/linux
where python   # Windows

Windowsでは where、mac／Linuxでは which を使って実行ファイルの場所を確認します。さらに pip が別のPythonを指していないか、python -m pip を使って確実に同じ環境へインストールするのが安全です。

python -m pip install requests

実際の現場でよくある「環境差」の話に入ります。ここを押さえると、多くのケースで一発解決します。

対処方法1.仮想環境とpipの整合性を取る¶

複数のPythonが入っていると、ターミナルで pip install したものが別のPython環境に入ってしまうことがあります。 これを避けるには、仮想環境を使って明確にするのが最も安全です。

仮想環境の作り方（例）は次の通り。これでプロジェクトごとに依存を分離できます。

python -m venv .venv
# mac/linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# その後
python -m pip install -U pip
python -m pip install requests

仮想環境をアクティベートした状態で python を実行すると、その環境のPythonが使われ、pip install も同じ環境に入ります。 実はこの「仮想環境の有無」が原因で長時間悩む人が多いのです。

次は実際に「インポートに失敗する具体例」とその修正を示します。コードを動かして試してみてください。

事例1：単純にインストール忘れ（最も基本的）¶

まずは初心者が最初に遭遇するケース。以下のスクリプトを作って実行すると、

# example1.py
import requests

print(requests.__version__)

ターミナルで python example1.py を実行したときに ModuleNotFoundError が出たら、単純に requests がそのPython環境に存在しません。 python -m pip install requests を実行してから再度試してください。

次は少しトリッキーなケースです。ファイル名の衝突は地味に厄介です。

事例2：自分のファイル名やディレクトリ名が原因¶

こんな経験はありませんか？

自作のファイル名が requests.py で、同じディレクトリに requests.py があるためにPythonがそちらを読み込もうとして別問題になる、といったものです。

例えば次のような構成だと危険です。

プロジェクト/
├─ requests.py
└─ app.py

app.py 内で import requests をすると、自分の requests.py を参照しようとします。結果として期待した外部ライブラリが使えずエラーや別の不具合が発生します。対策はシンプルで、ファイルやディレクトリの名前を他と被らないものに変えることです。

相対インポートの罠もよく見かけます。パッケージの体裁を整えていないと動かないことがあります。

事例3：相対インポートでModuleNotFoundErrorが出る¶

パッケージ構成で from .module import foo を使っているのに、直接 python module.py のように実行してしまうと、パッケージとして扱われず相対インポートが使えずに ModuleNotFoundError になることがあります。

正しい実行の例は以下の通りです。

# パッケージ構成
myapp/
  ├─ package/
  │   ├─ __init__.py
  │   ├─ a.py
  │   └─ b.py
  └─ run.py

# 実行方法（プロジェクトルートで）
python -m package.a

-m を使ってモジュールをパッケージとして実行するのがポイントです。 直接ファイルを実行すると相対インポート関連のエラーが出やすいので注意が必要です。

ここまででかなりのケースをカバーしました。次は、実務的な観点から有益な「チェックリスト」と「よくある原因と対策」を表で整理します。表は問題発見を早めるために便利です。

よくある原因と対策（一覧表）¶

ここで、原因とその対策を一目で見られるように表にまとめます。状況を見て対応を選んでください。

原因（症状）	どう確認するか	対策（すぐできること）
パッケージ未インストール (No module named 'xxx')	python -c "import pkgutil; print(pkgutil.find_loader('xxx'))" または python -m pip show xxx	python -m pip install xxx
pip と python の環境が異なる	which python / which pip / python -m pip --version を確認	python -m pip install ... を使う、仮想環境を利用
ファイル名・ディレクトリ名の衝突	プロジェクト直下に同名ファイルがないか確認	名前を変更、あるいはパッケージ化して整理
相対インポートの失敗	ModuleNotFoundError がパッケージ名で出る	python -m package.module のように実行、__init__.py を確認
パッケージのビルドエラー（C拡張など）	pip install のログを見る	ビルドツール（gcc等）をインストール、wheelを使う
PATH/PYTHONPATH 設定の問題	import sys; print(sys.path)	必要なら sys.path.append() で一時的に対応、永続的には環境変数やパッケージ化

ここからは、現場の「小技」と「トラブルシュート」—エンジニア歴10年の観点も踏まえた実践的ヒントを紹介します。

実務で役立つワザ¶

ここまで読んでくれた方に向けて、現場で役立つちょっとしたコツを紹介します。これらは実際のプロジェクトで私（執筆者が反映した一次情報）や現場の仲間が何度も使っているテクニックです。

まず、python -m pip を常に使う習慣をつけると、環境の不一致によるトラブルが激減します。コマンドラインで pip install ... と打つより確実です。次に、requirements.txt をプロジェクトルートに置き、CIや新規環境で python -m pip install -r requirements.txt を使う運用を標準化すると、チーム全員の環境差を減らせます。

また、Dockerを使う場合はイメージ内で python -m pip install を行い、ローカルの環境差を無視してコンテナ上で動作確認するのがベターです。CIでユニットテストを走らせるパイプラインを用意しておくと、依存関係の欠落を早期に発見できます。

次に、コマンドと実践的なデバッグ手順を短くまとめます。ここはすぐ使える「魔法のコマンド群」です。

すぐ使えるデバッグコマンド（短めに）¶

試す優先順位は以下の順です。箇条書きを最小限にして提示します。

• まずは今動いているPythonを確認：python -V と which python（Windowsは where python）
• 同じPythonでpipを使う：python -m pip install <パッケージ名>
• 仮想環境を作る：python -m venv .venv → アクティベートしてからインストール
• インポート経路を確認：Python REPLで import sys; print(sys.path)

ここまで読み進めて、「それでも直らない…」という場合のための最終チェックとFAQを用意しました。詰まったときに順番に確認すると、かなりの確率で原因が見つかります。

最終チェック（トラブルシュート順）¶

以下の内容をチェックしてみて、不具合がないか確認してみましょう。

1. エラーメッセージのモジュール名は正しいか（タイポはないか）。
2. python -m pip show <module> でインストール先が今のPythonか確認。
3. 仮想環境が有効か、または想定のPython実行ファイルか確認。
4. 自分のファイル名が標準や外部パッケージ名と衝突していないか確認。
5. 相対インポートを使っている場合、パッケージ構成と実行方法を見直す。
6. それでもダメなら pip install --upgrade pip setuptools wheel を試す（ビルド系の問題対応）。

最後に、よくある質問に短く答えます。疑問を投げかける形式で親しみやすくまとめます。

まとめ¶

最後にこの記事のポイントをシンプルにまとめます。Pythonの ModuleNotFoundError は大抵以下のどれかです：未インストール、環境のズレ、名前の衝突、相対インポートのミス、ビルド/依存の失敗。まずは「どのPythonが動いているか」を確認してから、python -m pip install や仮想環境を使うのが最短ルートです。

エラーは煩わしい存在ですが、原因を分解して一つずつ潰していくと確実に慣れてきます。焦らずに一歩ずつ進めていきましょう。

ここまでお読みいただきありがとうございました！