PythonのModuleNotFoundError: No module named 'xxx' を修正する

何が起きているのか

Pythonがインポート時にモジュールを見つけられない状態です。シンプルな話ですが、原因はさまざまです：パッケージが一度もインストールされていない、間違ったPython環境にインストールされた、pipとpythonのバイナリが異なる場所を指している、またはPyPIのパッケージ名とimport文で入力する名前が異なる、などが考えられます。

まず原因を特定しましょう。闇雲にインストールしても時間の無駄で、問題が解決しないことがほとんどです。

まずデバッグする

スクリプトを実行しているPythonバイナリを正確に確認しましょう：

which python
which python3
python --version
python3 --version

次に、その特定のPython向けにパッケージがすでにインストールされているか確認します：

python -m pip list | grep requests   # 'requests' を対象のモジュール名に変更してください

パッケージがリストに表示されているのにエラーが続く場合、それはpip/Pythonのミスマッチです。解決策3に直接進んでください。

解決策1：不足しているパッケージをインストールする

十中八九、パッケージが存在しないだけです。インストールしましょう：

pip install xxx

Python 2と3が共存するマシンでは、明示的に指定しましょう：

pip3 install xxx
# または、使用しているPythonバイナリに直接結びつける:
python -m pip install xxx
python3 -m pip install xxx

python -m pipはより安全な習慣です。シェルのPATHの混乱を回避し、その特定のPythonバイナリに属するpipを直接呼び出します。

解決策2：間違った仮想環境

インストールはしたけれど、間違った環境に入れてしまったケースです。誰もが一度は経験することです。

# 現在アクティブな仮想環境はあるか？
echo $VIRTUAL_ENV

# 正しい環境をアクティブにしてからインストール
source venv/bin/activate          # Linux/macOS
.\venv\Scripts\activate           # Windows

pip install xxx

Condaユーザーの場合：

conda activate myenv
pip install xxx
# または、condaレジストリにある場合:
conda install xxx

典型的なサイン：パッケージはエラーなくインストールされるのに、新しいターミナルを開くたびにModuleNotFoundErrorが繰り返し発生する。

解決策3：pip/Pythonバイナリのミスマッチ

多くのLinuxディストリビューションでは、素のpipはいまだにPython 2.7を指しています。パッケージをインストールしてもPython 3からは見えず、首をかしげることになります。

python -m pip install xxx

インストール後、Pythonが実際に検索する場所にあるか確認しましょう：

python -c "import xxx; print(xxx.__file__)"

表示されるパスは、アクティブな仮想環境またはPython 3.xのsite-packagesディレクトリ内にあるべきです。/usr/lib/python2.7/以下ではありません。

解決策4：pip名とimport名のミスマッチ

PyPIの名前とimport名は常に一致するとは限りません。pip installが成功しても、importで正しい名前を入力したとは限りません。よくある例：

• pip install Pillow → import PIL
• pip install scikit-learn → import sklearn
• pip install python-dateutil → import dateutil
• pip install opencv-python → import cv2
• pip install beautifulsoup4 → import bs4

不明な場合は、パッケージのPyPIページまたはREADMEを確認してください。import名は必ずそこに記載されています。

解決策5：ローカルモジュールがsys.pathにない

自作のモジュール（pipパッケージではない）の場合、Pythonがどこを探せばよいかわからないだけかもしれません：

import sys
print(sys.path)   # Pythonが検索するすべてのディレクトリを表示

手っ取り早い回避策：

import sys
sys.path.insert(0, '/absolute/path/to/your/project')
import xxx

より良い長期的な解決策：プロジェクトのルートからPythonを実行するか、パッケージを編集可能モードでインストールして常にimport可能にする：

pip install -e .

解決策6：Pythonバージョンの非互換性

tensorflow 2.xのようなパッケージはPython 3.7のサポートを廃止しました。pip install自体がエラーを出す場合は、よく読んでください。通常、必要なPythonバージョン範囲が明記されています。

まだお使いのPythonをサポートしている古いリリースを固定しましょう：

pip install "somepackage==1.2.3"   # お使いのPythonをサポートする最後のバージョン

修正の確認

# importは成功するか？
python -c "import xxx; print('OK')"

# どこにインストールされたか？
python -c "import xxx; print(xxx.__file__)"

# インストールされたバージョンは？
python -m pip show xxx

教訓

• python -m pip installをデフォルトにしましょう。素のpipは複数のPythonが共存するシステムでは落とし穴です。
• 作業を始める前に仮想環境をアクティブにしましょう。アクティブ化の忘れが「でも、もうインストールしたはずなのに！」という不満の少なくとも半分の根本原因です。
• requirements.txtをコミットしましょう。新鮮な環境でpip install -r requirements.txtを実行すれば、まったく同じ環境が再現できます。予期せぬ事態はありません。
• Python 3.10と3.11を並行して使う場合は、明示的にしましょう：python3.11 -m pip install xxxで曖昧さがなくなります。