pip installは成功したのに、JupyterでModuleNotFoundErrorになる場合は、Notebookを動かすPythonと、パッケージを入れたPythonが同じかを確認します。一方、セルを動かす前に「ipykernel パッケージが必要です」と表示される場合は、Notebook内でコマンドを実行できないため、ターミナルから対象のPythonを確認します。
カーネルはNotebookのコードを実行するプロセスで、ipykernelはPythonをJupyterのカーネルとして動かすパッケージです。ブラウザでNotebookが開けても、選択したPythonで必要なパッケージを使えるとは限りません。Jupyter公式のトラブルシューティングでも、サーバーとカーネルの環境の違いが問題の原因として案内されています。
エラーが出るタイミングから確認場所を選ぶ
| 症状 | 最初に確認すること | 操作する場所 |
|---|---|---|
| セル実行前に「ipykernelが必要」と表示される | 選択したPythonと、その環境のipykernel | ターミナル。次の節へ |
セルは動くがimportでModuleNotFoundErrorになる |
実行中Pythonとパッケージの導入先 | Notebookのセル。「NotebookのPythonと、インストール先を確認する」へ |
| 使いたい環境がカーネル候補にない | 環境の検出と、必要に応じたカーネル登録 | カーネル選択画面とターミナル。「導入済みの仮想環境へカーネルを切り替える」へ |
| ipykernel導入済みでも起動に失敗する | 選択先、依存の読み込みエラー、古い登録パス | ターミナルとエラーの詳細 |
ここで分けるのは、コードを実行するカーネルを起動できない段階と、起動後に必要なライブラリを読み込めない段階です。%pipは現在のカーネルでpipを実行するため、起動できない段階ではターミナル側の手順を使います。
「ipykernel パッケージが必要です」と表示される場合
VS Codeで選択しているPythonを確かめる
Notebook右上のカーネル名またはSelect Kernelを開き、使いたいPython環境を確認します。見つからなければSelect Another Kernel… → Python Environmentsを確認してください。Python Environmentsには、ipykernelがまだ入っていない環境も表示されます。
環境名だけでなくPython実行ファイルのパスを確認し、そのPythonをターミナルで指定します。VS CodeでPythonのNotebookを実行するために、対象環境へJupyter一式を入れ直す必要はありません。カーネルとして使うにはipykernelが必要です。これらの区別はVS Code公式のJupyterカーネル管理に基づきます。
対象Pythonで確認してからipykernelを入れる
次は、プロジェクト直下に既存の.venvがあり、それをNotebookでも使いたい場合の例です。プロジェクトのディレクトリで実行します。別の環境を使うなら、選択したPythonの実際のパスへ置き換えてください。
Windows PowerShell：
# 単独のpipが別環境を指す可能性があるため、Pythonのパスをそろえる。
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"
.\.venv\Scripts\python.exe -m pip show ipykernelmacOS / Linux：
# 単独のpipが別環境を指す可能性があるため、Pythonのパスをそろえる。
./.venv/bin/python -c "import sys; print(sys.executable)"
./.venv/bin/python -m pip show ipykernel意図したPythonで、ipykernelが未導入と確認できた場合に追加します。共有環境では導入ルールを確認してください。
Windows PowerShell：
.\.venv\Scripts\python.exe -m pip install ipykernelmacOS / Linux：
./.venv/bin/python -m pip install ipykernel対象Pythonを指定する方法は、Microsoftのipykernel依存不足の案内でも示されています。パスに空白がある場合、PowerShellでは& "C:\my project\.venv\Scripts\python.exe" -m pip show ipykernelのように呼び出し演算子&と引用符を使います。
.venvの実行ファイルが見つからなければ、先に実際の環境パスを確認します。No module named pipなら、その環境にはpipがないため、同じコマンドの再実行では進めません。uvやcondaで管理している環境は、プロジェクトの依存管理方法に沿ってipykernelを追加します。
導入済みなら、importできるか確認する
pip showで見つかっても起動しない場合は、同じPythonでipykernelの読み込みを確認します。
Windows PowerShell：
.\.venv\Scripts\python.exe -c "import ipykernel; print(ipykernel.__version__); print(ipykernel.__file__)"macOS / Linux：
./.venv/bin/python -c "import ipykernel; print(ipykernel.__version__); print(ipykernel.__file__)"成功したらNotebookでその環境を選び直し、セル内のsys.executableと、使いたいライブラリのimportを確認します。ipykernelを入れても、pandasなどの分析用ライブラリまで導入されるわけではありません。
失敗した場合はエラー全文を残し、末尾に出る不足モジュールや読み込み失敗を確認します。Microsoftのカーネル起動失敗の案内には、依存不足だけでなく、選択するPythonの誤りも挙げられています。WSLやリモート接続では、そのカーネルが動く側の環境を調べます。
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 pandasshowでは版と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 pandaspythonという名前が使えない環境では、普段利用しているpython3などに読み替えます。ただし、その名前がNotebookと同じPythonを選んでいるかは、出力で確認してください。
python -m pipは、そのpythonでpipを実行する書き方です。単独のpipがどのPythonに対応するか分からない場合に、実行先を明確にできます。pip User Guideがこの形式を案内しています。
次は環境が食い違う説明例です。実際のユーザー名やディレクトリは環境によって異なります。
| 確認場所 | Pythonの例 | pandasの状態 |
|---|---|---|
| インストールしたターミナル | C:\work\analysis\.venv\Scripts\python.exe |
導入済み |
| エラーが出るNotebook | C:\Python312\python.exe |
未導入 |
Pythonのバージョンが同じでも、別の仮想環境なら追加パッケージは異なり得ます。仮想環境とは、プロジェクトごとにPythonパッケージを分ける仕組みです。
図：Jupyter公式の環境の区別を基に、本記事の例として独自に図解。
確認結果から対処を選ぶ
| 確認できたこと | 対処 | 利点 | 注意点 |
|---|---|---|---|
| Notebookが目的の環境で、パッケージだけない | 現在の環境へ%pipで追加 |
カーネルを変えずに進められる | 共有環境や依存管理のルールを確認する |
| 別の仮想環境に必要なパッケージが揃っている | Notebookのカーネルを切り替える | 用意済みの環境を使える | 切替後に変数やセルを実行し直す |
| 目的の環境が候補に出ない | ipykernel導入・登録を確認 |
環境を選択肢へ追加できる | 実行するPythonを間違えない |
| 同じ環境にあるのに失敗する | 不足名・探索先・依存関係を調べる | 別原因を切り分けられる | 再インストールだけでは直らない場合がある |
インストール時に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は分けて運用できます。
目的の仮想環境が表示されない場合は、前半の手順で、その環境にipykernelが入り、読み込めることを確認します。VS CodeがPython環境を直接検出できる場合、手動の登録は必須ではありません。ブラウザのJupyterなどで必要な場合に、次のコマンドで登録します。以下は、プロジェクトに既存の.venvがあり、ipykernelの導入が済んでいる場合のターミナル用コマンドです。
Windows PowerShell：
# 別環境へ登録しないよう、仮想環境のPythonを明示する。
.\.venv\Scripts\python.exe -m ipykernel install --user --name analysis-project --display-name "Python (analysis-project)"macOS / Linux：
# 別環境へ登録しないよう、仮想環境のPythonを明示する。
./.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名を分ける
インストールする配布パッケージ名と、コードで読み込む名前は一致しない場合があります。
| インストールする配布名 | Pythonのimport名 |
|---|---|
pandas |
pandas |
Pillow |
PIL |
たとえば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から確認します。共有サーバーへの導入や設定変更は、その環境の管理ルールに従ってください。
既存の隔離環境検証と、今回の確認範囲
2026年9月11日の記事作成時に、Linux上に2つの仮想環境を用意し、一方だけにhumanizeを導入して、もう一方のIPythonカーネルから読み込む検証を行いました。GUIの操作確認とは分け、カーネルへコードを送って結果を確認しています。
| 検証操作 | 結果 |
|---|---|
ターミナル側の環境でimport humanize |
成功 |
未導入側のカーネルでimport humanize |
ModuleNotFoundError |
同じカーネルの%pipで導入 |
成功 |
| カーネル再起動後にimportと関数を実行 | 成功、12,345を出力 |
検証環境はPython 3.12.13、IPython 9.17.1、ipykernel 7.3.0、humanize 4.16.0です。パッケージ導入には事前取得したwheel（配布用ファイル）を使いました。これらは検証時の版であり、利用に必要な固定バージョンの指定ではありません。
今回の改稿では2026年10月19日に公式資料を再確認しました。Windows・macOSのGUI、VS Codeでのクリック操作、pandasを使うすべての環境は実測していません。読者の環境では、パスの一致に加えて、必要なパッケージのimportと処理の実行まで確認してください。
解消後は、環境を作り直せる状態にする
その場のインストールで直ったら、使った環境と依存関係をプロジェクトに残します。Notebookの冒頭に動作確認したPythonやパッケージの版を記録し、requirementsファイルや既存の依存管理ツールへ反映しておくと、別のPCでも同じ条件を用意しやすくなります。
pip・venvとuvの役割や既存環境の移行は、Pythonのuvとpip・venvの違い｜既存プロジェクトを移行する手順で整理しています。
コメント