Jupyterでインストール済みなのにModuleNotFoundErrorになる原因と対処法

pip installは成功したのに、Jupyter NotebookではModuleNotFoundErrorになる。そんなときは、Notebookを実行しているPythonと、パッケージを入れたPythonが同じかを確認します。現在の環境に追加するならNotebook内の%pipを使い、別の仮想環境に導入済みならNotebookのカーネルを選び直します。

カーネルとは、Notebookのコードを実行するプロセスです。ブラウザでNotebookが開けることと、そのカーネルで必要なパッケージが使えることは、確認する対象が異なります。Jupyter公式のトラブルシューティングでも、サーバーとカーネルの環境の違いが問題の原因として案内されています。

この記事は、Pythonのカーネルが起動し、セル内のimportで失敗する場合を対象にします。カーネル自体が起動しない場合は、後半の登録先の確認へ進んでください。操作説明は2026年9月11日時点の公式資料に基づき、コマンドの実測範囲は記事後半にまとめています。

NotebookのPythonと、インストール先を確認する

たとえば、次のエラーが出たとします。以下は説明用の例です。

ModuleNotFoundError: No module named 'pandas'

Notebookのセルで確認する

エラーが出るNotebookの新しいコードセルで実行します。

import sys

# カーネルの表示名では実行ファイルを区別できない場合があるため。
print(sys.executable)
print(sys.version)

sys.executableは、現在のPython実行ファイルのパスを表します。Python公式のsys.executableで確認できます。

続けて、別のセルで次を実行します。%pipはIPython（Pythonの対話実行機能）の専用構文なので、通常のターミナルや.pyファイルへそのまま貼り付けないでください。

%pip --version
%pip show pandas

showでは版とLocationを確認します。Package(s) not foundと出たら、このカーネルのpipではその配布パッケージを確認できていません。名前違いもあるため、これだけで破損と決めず、後半の対応表も確認します。

インストールしたターミナルで比較する

以前pip installしたターミナルで、次を実行します。Windows PowerShell、macOS、Linuxで、pythonが目的のPythonを指している環境向けです。

python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip show pandas

pythonという名前が使えない環境では、普段利用しているpython3などに読み替えます。ただし、その名前がNotebookと同じPythonを選んでいるかは、出力で確認してください。

python -m pipは、そのpythonでpipを実行する書き方です。単独のpipがどのPythonに対応するか分からない場合に、実行先を明確にできます。pip User Guideがこの形式を案内しています。

次は環境が食い違う説明例です。実際のユーザー名やディレクトリは環境によって異なります。

Pythonのバージョンが同じでも、別の仮想環境なら追加パッケージは異なり得ます。仮想環境とは、プロジェクトごとにPythonパッケージを分ける仕組みです。

図：Jupyter公式の環境の区別を基に、本記事の例として独自に図解。

確認結果から対処を選ぶ

インストール時にRequirement already satisfiedと出ても、そのpipが参照する場所で条件を満たしたという情報です。Notebookからの読み込み成功は、カーネル側で別に確認します。

図：本記事の確認順序を独自に整理。導入済みの場合の追加確認は後半で扱います。

今のカーネルにパッケージを追加する

自分で管理する環境で、現在のカーネルを使い続ける場合は、Notebookのセルで実行します。ここではpandasが必要な例を使います。

%pip install pandas

プロジェクトで版が指定されている場合は、その制約に従ってください。既にuvやcondaで依存関係を管理しているなら、管理ファイルや環境定義にも変更を反映します。

%pipは現在のカーネルでpipを動かす機能です。!pip install ...はシェルを通じたコマンド実行なので、コマンド検索の設定次第で別のpipを呼ぶ可能性があります。IPythonのmagic commandsを参照してください。

インストールが成功したらNotebookを保存し、カーネルを再起動します。再起動するとメモリ上の変数は失われるため、必要なセルを先頭から実行し直します。ブラウザの再読み込みだけでは、カーネルが再起動されないことがあります。

確認用セルは次のとおりです。

import sys
import pandas as pd

# 意図した環境から読み込めたか、版だけでなく場所も確認する。
print(sys.executable)
print(pd.__version__)
print(pd.__file__)

importが成功し、__file__が想定した環境のパッケージを指していれば、今回の読み込みエラーは解消できています。導入前後で出力を残しておくと、カーネルの選び間違いにも気づきやすくなります。パスが同じでも、別ホストの同名パスや起動時の設定まで同じとは限らないため、最後は実際のimportで確認します。

%pipが見つからない場合は、Python/IPythonのカーネルを選んでいるか確認します。No module named pipなら、その環境の作成・管理方法に従ってpipを用意します。権限エラーや管理対象環境のエラーが出た場合は、管理者権限や--break-system-packagesで押し通さず、自分の仮想環境を選ぶか管理者へ確認してください。

導入済みの仮想環境へカーネルを切り替える

VS Codeの場合

.ipynbを開き、右上のカーネル名またはSelect Kernelを押します。目的の環境が見えなければSelect Another Kernel…からPython EnvironmentsやJupyter Kernelsを確認します。

コマンドパレットのNotebook: Select Notebook Kernelからも選択できます。通常のPythonファイル用のインタープリター選択だけで完了とせず、Notebook自身のカーネルを確認してください。選択後、先ほどのsys.executableのセルを実行します。

画面の選択肢と操作はVS Code公式のJupyterカーネル管理に基づきます。表示名や並び順は環境によって異なります。

ブラウザのJupyter Notebook / JupyterLabの場合

Notebookのカーネル名表示やKernelメニューから、カーネルを変更する項目を選びます。ブラウザで開くJupyterの環境と、セルを実行するPythonは分けて運用できます。

目的の仮想環境が表示されない場合は、その環境のPythonへipykernel（PythonをJupyterのカーネルとして動かすパッケージ）を入れ、必要に応じて登録します。VS CodeがPython環境を直接検出できる場合、手動の登録は必須ではありません。以下は、プロジェクトに既存の.venvがある場合のターミナル用コマンドです。

Windows PowerShell：

# 別環境へ登録しないよう、仮想環境のPythonを明示する。
.\.venv\Scripts\python.exe -m pip install ipykernel
.\.venv\Scripts\python.exe -m ipykernel install --user --name analysis-project --display-name "Python (analysis-project)"

macOS / Linux：

# 別環境へ登録しないよう、仮想環境のPythonを明示する。
./.venv/bin/python -m pip install ipykernel
./.venv/bin/python -m ipykernel install --user --name analysis-project --display-name "Python (analysis-project)"

analysis-projectは例なので、自分のプロジェクトで使う未使用の名前へ置き換えます。同じ--nameを指定すると既存の登録を上書きします。--display-nameは画面に出す表示名です。登録によって他の環境のパッケージがコピーされるわけではなく、このPythonを起動するための情報が作られます。IPython公式のカーネル登録に手順が説明されています。

登録後に候補を開き直し、目的のカーネルを選択してsys.executableとimportを確認します。

環境を移動・削除してから起動できなくなった場合は、Jupyterを動かしている環境のターミナルでjupyter kernelspec listを確認します。登録先のkernel.jsonにあるargvが、古いPythonを指している可能性があります。不要な登録をまとめて消す前に、対象の名前とパスを確かめてください。

同じ環境なのに読み込めないとき

pipで指定する名前とimport名を分ける

インストールする配布パッケージ名と、コードで読み込む名前は一致しない場合があります。

たとえばPillowを導入してimport Pillowと書いても、期待した読み込みにはなりません。配布名とimport名の関係は、使うライブラリの公式導入手順で確認します。Python Packaging User Guideの説明にも両者の区別があります。

エラーメッセージに出た名前を、そのままpip installへ渡すのは避けてください。名前だけでは、どの配布パッケージを入れるべきか確定できません。

最後のエラー行で、不足している名前を読む

import pandasから始まった処理でも、内部で読み込む別のパッケージが不足している場合があります。トレースバック（エラーに至る呼び出しの履歴）の最後にあるNo module named '...'の名前を確認してください。

依存関係の宣言と導入状態を調べるには、Notebook内で次を実行します。

%pip check

これは宣言された依存の不足や版の不整合を調べる補助になります。ただし、任意機能の依存や実際のimportの成功まで保証するものではありません。pip checkの公式説明も参照してください。

また、ImportError: DLL load failedなどのネイティブライブラリ読み込み失敗は、単純なモジュール未発見とは確認項目が異なります。エラー全文を残し、該当ライブラリのOS・Python対応条件を調べます。Pythonの例外一覧ではModuleNotFoundErrorとImportErrorの関係を確認できます。

自作ファイル名と探索先を確認する

Notebookの近くにpandas.pyやpandasフォルダーを作っていると、導入したパッケージより先に読み込まれることがあります。名前の衝突が疑わしい場合は、読み込み先や現在の作業ディレクトリを調べます。

from pathlib import Path
import sys

print(Path.cwd())
print(sys.path)

自作ファイルの名前が衝突していれば変更し、カーネルを再起動して確認します。自作モジュールが見つからない場合も、ファイルの位置と探索先を確認してください。理由を確かめずにsys.pathへ他の仮想環境のsite-packagesを追加すると、版の組み合わせを崩す原因になります。Python公式のモジュール探索パスが仕組みを説明しています。

WSL・コンテナ・リモートサーバーを使っている場合

Windows側のターミナルに導入したパッケージが、WSL（Windows上のLinux環境）やリモートのカーネルへも導入されるわけではありません。VS Codeで別のJupyterサーバーへ接続している場合も、インストール先はそのサーバー側で考えます。

この場合も、Notebook内のsys.executableと%pip --versionから確認します。共有サーバーへの導入や設定変更は、その環境の管理ルールに従ってください。

隔離した環境で確認したこと

本記事ではLinux上に2つの仮想環境を用意し、一方だけにhumanizeを導入して、もう一方のIPythonカーネルから読み込む検証を行いました。GUIの操作確認とは分け、カーネルへコードを送って結果を確認しています。

検証環境はPython 3.12.13、IPython 9.17.1、ipykernel 7.3.0、humanize 4.16.0です。パッケージ導入には事前取得したwheel（配布用ファイル）を使いました。これらは検証時の版であり、利用に必要な固定バージョンの指定ではありません。

Windows・macOSのGUI、VS Codeでのクリック操作、pandasを使うすべての環境は実測していません。読者の環境では、パスの一致に加えて、必要なパッケージのimportと処理の実行まで確認してください。

解消後は、環境を作り直せる状態にする

その場のインストールで直ったら、使った環境と依存関係をプロジェクトに残します。Notebookの冒頭に動作確認したPythonやパッケージの版を記録し、requirementsファイルや既存の依存管理ツールへ反映しておくと、別のPCでも同じ条件を用意しやすくなります。

pip・venvとuvの役割や既存環境の移行は、Pythonのuvとpip・venvの違い｜既存プロジェクトを移行する手順で整理しています。