ModuleNotFoundErrorの原因と直し方｜No module named

ModuleNotFoundError: No module named 'xxx' は、「いま動いている Python」が探す場所（sys.path）のどこにも、そのモジュールが無いときに出るエラーです。 pip install したのに出る場合のほとんどは、pip で入れた先の Python と、実行している Python が別物になっています。

まずは、実行している Python と同じ Python で入れ直します。

python -m pip install パッケージ名     # pip ではなく「python -m pip」で入れる
python あなたのスクリプト.py           # 同じ python で実行する

それでも直らない場合は、原因が次のどれかです。この記事では、それぞれを Python 3.14 で実際に起こし、出たメッセージと直し方を並べました。最後に、原因を一発で切り分けるスクリプトも載せています。

確認環境：Ubuntu 24.04、Python 3.14.7（venv）、Python 3.11・3.12（比較用）、pip 26.2.1（確認日 2026年10月10日）。

原因の早見表

原因1：インストールしていない

$ python3.14 -c 'import tabulate'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import tabulate
ModuleNotFoundError: No module named 'tabulate'

いちばん単純なケースです。python -m pip install tabulate で入れます。pip install ではなく python -m pip にする理由は、次の原因2にあります。

原因2：pip で入れた先と、実行している Python が違う

venv（仮想環境）の中に tabulate を入れ、venv の外の Python で実行すると、同じパソコンの中でも見つかりません。

$ python3.14 -m venv .venv
$ . .venv/bin/activate
(.venv) $ python -m pip install tabulate
(.venv) $ python -c 'import tabulate; print(tabulate.__file__)'
/tmp/s8/.venv/lib/python3.14/site-packages/tabulate/__init__.py

$ python3.14 -c 'import tabulate'          ← venv の外の Python で実行
ModuleNotFoundError: No module named 'tabulate'

Python はバージョンごと・venv ごとに、パッケージの置き場所（site-packages）を別に持っています。 pip コマンドがどの Python につながっているかは、pip --version の末尾で分かります。

(.venv) $ pip --version
pip 26.2.1 from /tmp/s8/.venv/lib/python3.14/site-packages/pip (python 3.14)

よくある食い違い

Jupyter の %pip は、ノートブックが使っている Python に入れるための命令です。!pip はシェルの pip を呼ぶため、カーネルと別の Python に入ることがあります。

原因3：パッケージ名と import 名が違う

pip install する名前と、import で書く名前は一致しないことがあります。

(.venv) $ python -m pip install python-dateutil
(.venv) $ python -c 'import python_dateutil'
ModuleNotFoundError: No module named 'python_dateutil'

(.venv) $ python -c 'import dateutil; print(dateutil.__version__)'
2.9.0.post0

エラーメッセージの名前（No module named 'yaml'）をそのまま pip install yaml すると、別のパッケージを入れてしまうことがあります。import 名からパッケージ名を調べるには、パッケージの公式ドキュメントか PyPI のページを確認します。インストール済みのものは python -m pip show パッケージ名 で、入っている場所も分かります。

import Numpy のような大文字小文字の違いも同じエラーです（正しくは numpy）。

原因4：自作のモジュールが見つからない

次の構成で、app/main.py から app/util.py を読み込むとします。

proj/
├─ app/
│  ├─ __init__.py
│  ├─ main.py      ← from app.util import greet
│  └─ util.py
└─ scripts/
   └─ run.py       ← from app.util import greet

$ python3.14 app/main.py
Traceback (most recent call last):
  File "/tmp/s8/proj/app/main.py", line 1, in <module>
    from app.util import greet
ModuleNotFoundError: No module named 'app'

$ python3.14 -m app.main
hello

python ファイル.py で実行すると、sys.path の先頭に入るのは「そのファイルがあるフォルダ」（proj/app）です。 そこに app フォルダは無いので見つかりません。プロジェクトの一番上（proj）で python -m app.main と実行すると、カレントディレクトリが sys.path の先頭に入り、app パッケージが見つかります。

scripts/run.py のように、パッケージの外から使う場合も同じです。

$ python3.14 scripts/run.py
ModuleNotFoundError: No module named 'app'

$ PYTHONPATH=. python3.14 scripts/run.py
script: hello

その場しのぎなら PYTHONPATH で一番上を足せます。チームで使うなら、プロジェクトを「編集可能インストール」しておくと、どこから実行しても見つかります。

# pyproject.toml（最小構成）
[project]
name = "myapp"
version = "0.1.0"

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
packages = ["app"]

(.venv) $ python -m pip install -e .
(.venv) $ python scripts/run.py
script: hello

スクリプトの中で sys.path.append(...) を書いて直すこともできますが、実行する場所によって動いたり動かなかったりするため、python -m か編集可能インストールにするほうが確実です。

原因5：相対 import を、スクリプトとして実行した

$ python3.14 app/rel.py          ← 中身は from . import util
Traceback (most recent call last):
  File "/tmp/s8/proj/app/rel.py", line 1, in <module>
    from . import util
ImportError: attempted relative import with no known parent package

$ python3.14 -m app.rel
hello

エラー名は ImportError ですが、原因4と同じく実行のしかたの問題です。from . import は「自分が属するパッケージ」を基準にするため、パッケージとして実行（python -m app.rel）する必要があります。

原因6：標準ライブラリと同じ名前のファイルを作った

random.py という名前で自分のファイルを作ると、import random が自分自身を読み込みます。

$ python3.14 random.py
Traceback (most recent call last):
  File "/tmp/s8/shadow/random.py", line 1, in <module>
    import random
  File "/tmp/s8/shadow/random.py", line 2, in <module>
    print(random.randint(1, 6))
          ^^^^^^^^^^^^^^
AttributeError: module 'random' has no attribute 'randint' (consider renaming '/tmp/s8/shadow/random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module)

Python 3.13 以降は「標準ライブラリと同じ名前なので名前を変えて」と表示されます。Python 3.11 では次のように循環 import として表示され、原因が分かりにくくなります。

$ python3.11 random.py
AttributeError: partially initialized module 'random' has no attribute 'randint' (most likely due to a circular import)

random.py、json.py、email.py、test.py、requests.py、pandas.py のような名前のファイルやフォルダを作らないようにします。名前を変えたら、同じフォルダの __pycache__ も消しておきます。

原因7：pip install が externally-managed-environment で止まる

Ubuntu 24.04 などで、OS の Python に直接 pip install すると、次のエラーで止まります。

$ python3.12 -m pip install tabulate
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

OS が使っている Python を、pip の変更から守る仕組み（PEP 668）です。インストールが止まった結果、あとで ModuleNotFoundError になります。venv を作ってその中に入れるのが正しい対処です。

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install tabulate

--break-system-packages を付けると入りますが、OS のパッケージと衝突するおそれがあるため、作業用のコンテナなど使い捨ての環境に限るのが無難です。

切り分けスクリプト：どの Python が、どこを探しているか

原因が分からないときは、次のスクリプトをエラーが出る環境で実行します。

"""ModuleNotFoundError の切り分け：python check_module.py モジュール名"""
import importlib.util
import subprocess
import sys

name = sys.argv[1] if len(sys.argv) > 1 else 'requests'

print('実行中の Python :', sys.executable)
print('バージョン      :', sys.version.split()[0])
print('venv の中か     :', sys.prefix != sys.base_prefix)
print('探す場所 (sys.path):')
for p in sys.path:
    print('   ', p or '(カレントディレクトリ)')

spec = importlib.util.find_spec(name.split('.')[0])
print(f'{name} の場所   :', spec.origin if spec else '見つからない')

pip = subprocess.run([sys.executable, '-m', 'pip', '--version'], capture_output=True, text=True)
print('この Python の pip:', pip.stdout.strip() or pip.stderr.strip().splitlines()[-1])

venv の外と中で tabulate を調べた結果です。

$ python3.14 check_module.py tabulate
実行中の Python : /root/.local/bin/python3.14
バージョン      : 3.14.7
venv の中か     : False
探す場所 (sys.path):
    /tmp/s8
    /root/.local/share/uv/python/cpython-3.14.7-linux-x86_64-gnu/lib/python314.zip
    /root/.local/share/uv/python/cpython-3.14.7-linux-x86_64-gnu/lib/python3.14
    /root/.local/share/uv/python/cpython-3.14.7-linux-x86_64-gnu/lib/python3.14/lib-dynload
    /root/.local/share/uv/python/cpython-3.14.7-linux-x86_64-gnu/lib/python3.14/site-packages
tabulate の場所   : 見つからない
この Python の pip: pip 26.2.1 from /root/.local/share/uv/python/cpython-3.14.7-linux-x86_64-gnu/lib/python3.14/site-packages/pip (python 3.14)

$ .venv/bin/python check_module.py tabulate
実行中の Python : /tmp/s8/.venv/bin/python
バージョン      : 3.14.7
venv の中か     : True
探す場所 (sys.path):
    /tmp/s8
    ...（標準ライブラリの3行は同じ）
    /tmp/s8/.venv/lib/python3.14/site-packages
tabulate の場所   : /tmp/s8/.venv/lib/python3.14/site-packages/tabulate/__init__.py
この Python の pip: pip 26.2.1 from /tmp/s8/.venv/lib/python3.14/site-packages/pip (python 3.14)

同じことは、次のコマンドでも確かめられます。

環境別のチェックポイント

よくある質問

Q. pip install と python -m pip install はどちらを使うべきですか。 A. python -m pip install を使うと、その python と同じ Python に必ず入ります。Python が複数ある環境では、こちらが確実です。

Q. requirements.txt から入れたのに出ます。 A. python -m pip install -r requirements.txt を、実行するのと同じ Python（venv）で行ったかを確認します。requirements.txt にそのパッケージが書かれているかも確認します（パッケージ名と import 名が違う場合は、パッケージ名で書きます）。

Q. init.py は必要ですか。 A. Python 3.3 以降は __init__.py が無いフォルダも「名前空間パッケージ」として import できます。ただし、テストツールの探し方や、同じ名前のフォルダが複数あるときの動きが変わるため、自作のパッケージには置いておくのが分かりやすい形です。

Q. No module named 'xxx.yyy' のように、ドットの後ろが見つからないと言われます。 A. 親の xxx は見つかっているが、その中に yyy が無い状態です。サブモジュールの名前の綴り、パッケージのバージョン（そのサブモジュールがある版か）、同名の自作ファイルが親を隠していないかを確認します。

まとめ

• 原因の多くは「pip で入れた Python」と「実行している Python」の食い違い。python -m pip install で、実行するのと同じ Python に入れる
• venv は有効にしてから入れて、実行する。IDE・Jupyter・cron は別の Python を使っていないか確認する
• パッケージ名と import 名は違うことがある（PyYAML → yaml、Pillow → PIL、scikit-learn → sklearn）
• 自作モジュールは、プロジェクトの一番上で python -m パッケージ.モジュール、またはプロジェクトを pip install -e .
• 標準ライブラリと同じ名前のファイル（random.py など）を作らない。Python 3.13 以降は名前を変えるよう案内が出る
• 迷ったら sys.executable・sys.path・importlib.util.find_spec を表示する切り分けスクリプトで確かめる

参考・出典

確認日はいずれも 2026年10月10日です。

• Python ドキュメント「ModuleNotFoundError」：https://docs.python.org/ja/3/library/exceptions.html#ModuleNotFoundError
• Python ドキュメント「The initialization of the sys.path module search path」：https://docs.python.org/3/library/sys_path_init.html
• Python ドキュメント「venv — 仮想環境の作成」：https://docs.python.org/ja/3/library/venv.html
• Python ドキュメント「What's New In Python 3.13（標準ライブラリと同名のスクリプトのエラーメッセージ）」：https://docs.python.org/3/whatsnew/3.13.html
• Python ドキュメント「importlib.util.find_spec」：https://docs.python.org/ja/3/library/importlib.html#importlib.util.find_spec
• pip ドキュメント「User Guide」：https://pip.pypa.io/en/stable/user_guide/
• PEP 668「Marking Python base environments as "externally managed"」：https://peps.python.org/pep-0668/
• IPython ドキュメント「%pip マジックコマンド」：https://ipython.readthedocs.io/en/stable/interactive/magics.html
• setuptools ドキュメント「Development Mode (a.k.a. Editable Installs)」：https://setuptools.pypa.io/en/latest/userguide/development_mode.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。