この記事の要点

Python の ModuleNotFoundError: No module named '~'; '~' is not a package 原因の典型: 対象のパッケージディレクトリに __init__.py が無い（古い Python 3.2 以前ルール） 対処1: __init__.py（空でも OK）を作る 対処2: import パスの typo を疑う / sys.path に対象ディレクトリが入っているか確認 対処3: パッケージ未インストール → pip install パッケージ名

エラー内容

ModuleNotFoundError: No module named 'mypackage'

# または
ModuleNotFoundError: No module named 'mypackage'; 'mypackage' is not a package

# または
ImportError: cannot import name 'foo' from 'mypackage'

原因の切り分け

原因	確認方法	対処
パッケージ未インストール	pip list | grep xxx	pip install xxx
仮想環境を有効化していない	which python	conda activate / source venv/bin/activate
__init__.py が無い	ディレクトリ確認	空の __init__.py 作成
import パスの typo	正確なパッケージ名を確認	正しいパスに修正
sys.path にない	print(sys.path)	sys.path.append or PYTHONPATH
循環インポート	import 構造を見る	import を関数内に移動

対処1: パッケージインストール

# 現在の Python と pip を確認
which python
which pip
python --version

# パッケージインストール
pip install requests
pip install pandas==2.0.3      # バージョン指定
pip install -r requirements.txt

# 仮想環境で実行している場合、有効化を忘れない
conda activate myenv
# または
source .venv/bin/activate

# 入っているか確認
pip list | grep requests
pip show requests

対処2: __init__.py を作る

独自パッケージを作るとき、ディレクトリにこのファイルがないと「パッケージとして認識されない」ことがあります:

myproject/
├── main.py
└── mypackage/
    ├── __init__.py        ← ★ これが必要
    ├── module1.py
    └── module2.py

# main.py
from mypackage import module1
# または
from mypackage.module1 import some_function

# __init__.py は空でも OK
# 中身を書く場合
# mypackage/__init__.py
from .module1 import some_function  # パッケージ直下で公開
from .module2 import another_function

__all__ = ['some_function', 'another_function']
__version__ = '1.0.0'

注: Python 3.3+ では「名前空間パッケージ」として __init__.py なしでも動くことがありますが、明示的に作っておく方が安全。

対処3: sys.path を確認・追加

import sys

# 現在の検索パス
print(sys.path)
# 出力例:
# ['', '/usr/lib/python3.11', '/usr/lib/python3.11/site-packages', ...]

# 動的に追加
import os
sys.path.append(os.path.join(os.path.dirname(__file__), '..'))

# パスを先頭に追加（優先度高）
sys.path.insert(0, '/path/to/mypackage')

# pathlib 経由
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent))

対処4: PYTHONPATH 環境変数

# 一時的に
export PYTHONPATH="/path/to/mypackage:$PYTHONPATH"
python main.py

# Windows
set PYTHONPATH=C:\path\to\mypackage;%PYTHONPATH%

# 永続化（.bashrc / .zshrc に）
echo 'export PYTHONPATH="$HOME/code/mypackage:$PYTHONPATH"' >> ~/.bashrc

# VS Code の settings.json
{
    "python.envFile": "${workspaceFolder}/.env"
}

# .env
PYTHONPATH=./src

対処5: 名前空間の衝突

標準ライブラリやインストール済みパッケージと同じ名前のファイル/フォルダを作るとエラーになります:

myproject/
├── main.py
├── json.py                 ← ★ NG: 標準ライブラリ json と名前が衝突
└── ...

# main.py で
import json                 # myproject/json.py を読みに行ってしまう
                            # → ImportError や謎の挙動

# 解決: ファイル名を変更
# json.py → my_json.py

対処6: 循環インポート

# ❌ NG: 循環インポート
# a.py
from b import bar
def foo(): return bar() + 1

# b.py
from a import foo
def bar(): return foo() + 1

# → ImportError: cannot import name 'foo' from partially initialized module

# ✅ 解決1: 関数内インポート（遅延ロード）
# a.py
def foo():
    from b import bar
    return bar() + 1

# ✅ 解決2: 設計を見直して片方向に

対処7: パッケージインストール構造を整える

自作パッケージを pip install -e . で開発インストールすると path 問題が解消:

myproject/
├── setup.py
├── pyproject.toml
└── src/
    └── mypackage/
        ├── __init__.py
        └── ...

# setup.py
from setuptools import setup, find_packages

setup(
    name='mypackage',
    version='0.1.0',
    package_dir={'': 'src'},
    packages=find_packages(where='src'),
    install_requires=['requests', 'pandas'],
)

# 開発インストール（コード変更が即反映）
cd myproject/
pip install -e .

# 以降、どこからでも from mypackage import ... で使える

VS Code / PyCharm でのインタプリタ設定

• VS Code: Ctrl+Shift+P → "Python: Select Interpreter" で仮想環境を選択
• PyCharm: Settings → Project → Python Interpreter で選択
• 正しいインタプリタが選ばれていないと、CLI では動くのに IDE では import エラーが出る

デバッグ Tips

# どの Python が使われているか
import sys
print(sys.executable)            # /usr/bin/python3
print(sys.version)               # 3.11.0
print(sys.path)                  # 検索パス一覧

# パッケージがどこにあるか
import numpy
print(numpy.__file__)            # /path/to/numpy/__init__.py
print(numpy.__version__)

# pip 経由でファイル一覧
# pip show -f mypackage

関連エラー

• ImportError: cannot import name 'X' from 'Y': モジュールはあるが特定の名前が無い → バージョン違い / __all__ の確認
• AttributeError: module 'X' has no attribute 'Y': 同上
• RecursionError: maximum recursion depth exceeded: 循環インポート由来のことあり
• ModuleNotFoundError でなく ImportError: パッケージはあるが何か壊れている（再インストール）