【Python】pipで入れたのにimportできないときのトラブルシューティング

PythonのTopに戻る

pipのインストールが成功しても、importが成功するとは限らない。まずエラーの種類と、どのモジュール名で失敗したかを確認する。別のPythonへ入れた、import名を取り違えた、自作ファイルを読み込んだ、依存先やバイナリに問題がある、といった原因では対処が違う。何度も入れ直す前に、症状を分けて調べよう。

エラーの末尾だけで原因を決めない

ModuleNotFoundErrorは、指定した名前が検索経路から見つからない場合に発生する。ただし、自分がimportしたライブラリの内部で別のモジュールが不足している場合にも発生する。例外のname属性と、トレースバックで最後にどのファイルを実行していたかを確認することが大切である。

importの症状と最初に確認する場所
症状 最初の確認 次に行うこと
指定名がModuleNotFoundError 実行中のPython、import名 同じPythonのpipで配布名を確認する
別名がModuleNotFoundError 失敗した依存先の名前 依存関係や追加機能の導入条件を確認する
cannot import nameなどのImportError 読み込み元、公開される名前 APIの変更、循環import、名前衝突を調べる
DLL・共有ライブラリ・ABI関連の失敗 Python・依存先・OSの組合せ 該当ライブラリの互換性案内を確認する

同じImportErrorでも、削除された関数を古いコードから呼んでいる場合と、拡張モジュールの読み込みに失敗した場合では修正する対象が異なる。全文を残し、最初に失敗したimport文と最後の例外を対応させて読む。

不足している名前を小さな例で確認する

次の例は、存在しない練習用モジュールを指定して例外の属性を確認するものだ。tip_missing_example_2026は実在の配布パッケージを探すための名前ではない。見知らぬエラー名をそのままpip installへ渡すことは避け、利用中ライブラリの公式手順で必要な配布名を確かめる。

example.py

import importlib

name = "tip_missing_example_2026"
try:
    importlib.import_module(name)
except ModuleNotFoundError as exc:
    print("requested:", name)
    print("missing:", exc.name)
    print("same name:", exc.name == name)
    assert exc.name == name
else:
    raise AssertionError("This practice module should not exist")

# 標準ライブラリの正常な読み込みも確認する
module = importlib.import_module("json")
assert module.loads('{"ok": true}') == {"ok": True}
print("json import: OK")

実行結果

requested: tip_missing_example_2026
missing: tip_missing_example_2026
same name: True
json import: OK

この例では要求した名前と不足名が一致する。実際の解析コードで不足名が違うなら、ライブラリ本体は見つかったものの、その内部で失敗した可能性がある。except Exceptionで隠したり、すべてを「未インストール」と表示したりすると、重要な情報が失われる。

実行環境・名前・読み込み元の順に調べる

まず、失敗するプログラム自身でsys.executableを表示する。ターミナルのpythonと、エディターやノートブックで選ばれたPythonが同じとは限らない。その実行ファイルに対して-m pipを使い、パッケージが入っているかを調べる。詳しい照合方法は関連する環境診断の記事にまとめた。

次に、インストールに使う配布名とimport名を公式ドキュメントで照合する。二つの名前が違うこと自体は異常ではない。また、json.pyやrandom.pyなど標準ライブラリと同名の自作ファイルが作業フォルダーにあると、そちらを読み込むことがある。importできた場合はモジュールの__file__で読み込み元を確認できる。

find_specは場所を調べる補助になるが、存在することと正常に読み込めることは別である。特にドットを含むサブモジュール名では親パッケージを読み込む場合がある。調査目的でも、信頼できないモジュールをむやみにimportしないようにしたい。

互換性の問題は組合せで直す

NumPyなどの拡張モジュールでは、Pythonの版、OS、CPUの種類、依存先のABIの組合せが関係する。pipが示す依存条件を満たしていても、すべての読み込み時エラーを検出できるわけではない。エラーに登場するパッケージとバージョンを記録し、その公式の互換性情報を調べる。

この段階で既存環境の全パッケージを一括更新すると、別の解析コードまで動かなくなる可能性がある。小さなvenvに必要最小限を入れ、再現するか確かめる方が切り分けやすい。手元の問題を確認せず、特定バージョンへの降格を万能な対処として実行しないことが重要である。

修正した後は新しいプロセスで確認する

環境やファイル名を修正したら、まず短いimportだけのプログラムを新しいPythonプロセスで実行する。ノートブックでは選択中のカーネルを確認し、必要なら再起動する。すでに読み込まれたモジュールが残っていると、変更後の状態を見ているつもりで以前の状態を確認してしまう。

最小のimportが通ったら、必要な関数の呼び出し、最後に元の解析を試す。どの段階で直ったかが分かれば、再インストールだけを繰り返すより次回の調査が速くなる。本記事の実行例は名前不足の確認であり、OS別のバイナリ不整合を実機で再現したものではない。

動作確認と参考資料

掲載例はLinux・CPython 3.12.14で動作確認した。OS固有のコマンドや環境ごとに変わるパスは、本文中の条件を確認して使ってほしい。

関連するTips

PythonのTopに戻る