python学習⑦｜ModuleNotFoundErrorとpipが認識されない時の対処法 | 黄昏の戯れ

pythonを学び始めて最初に心が折れそうになったのは、ライブラリのパスエラーだった――というのが、正直な実感です。真っ赤なTracebackがずらっと表示された瞬間、何が起きているのか分からず、頭が真っ白になった経験があります。

でも安心してください。ModuleNotFoundErrorも、pipが「認識されません」と出るエラーも、気づいたら複数のpython環境が混在してわけが分からなくなっている状態も、初心者が一度は通る道です。この記事では、次のことが分かります。

ModuleNotFoundErrorが出る理由
pip installしたのにimportできない理由
pipコマンドが「認識されません」と出る理由
すでに複数のpython・pip環境が混在してしまった状態からの復旧方法

中の人

実は私も、初めて真っ赤なTracebackを見たときは画面を閉じたくなったんだよね……。でも大丈夫、1つずつ見ていけば怖くないから一緒に見ていこう!

ライブラリのエラーで心が折れそうになった話
ModuleNotFoundError「No module named ‘xxx’」とは?原因と直し方
pip installが「認識されない」・pip/pythonコマンドが見つからないときの対処法
複数のpython/pip環境が混在して「今どれを使っているか」分からなくなったときの整理法
すでに環境がぐちゃぐちゃに混在してしまった状態からの復旧手順
これも知っておきたい、python初心者がよくつまずく基本エラー8選
豆知識、知っておくと安心なエラーの話
まとめ:エラーが出たときの自己診断チェックリスト

ライブラリのエラーで心が折れそうになった話

正直に告白すると、pythonを学び始めて最初に心が折れそうになったのは、ライブラリのパスエラーだった、というのが私自身の経験です。importの一行を書いただけなのに、画面いっぱいに赤い文字のTracebackが表示され、英語の羅列を前にして思考が止まりました。「もしかして自分には向いていないのかもしれない」「何か大事なものを壊してしまったのでは」と、必要以上に自分を責めてしまったのを覚えています。

結論から言うと、これは特別なことでも失敗でもありません。エラーは初心者だけでなく、プログラミングを仕事にしている人でも日常的に目にするものです。Tracebackの赤字は「あなたの能力不足」を示すサインではなく、「python」というプログラムが「ここで処理を続けられませんでした」と教えてくれているだけの、いわば案内表示のようなものです。

この記事では、python学習でつまずきやすい代表的な3つのテーマ、「ModuleNotFoundErrorが出る理由」「pipコマンドが認識されない理由」「複数のpython・pip環境が混在してしまったときの整理・復旧の方法」を、実際のエラー文言や手順に沿って順番に見ていきます。

この記事は、python学習①(コードの記述)から続く「python学習⑦」です。変数・if文・リスト・タプル・for文とここまで学んできた方の次の壁として書いています。

中の人

よし、ここからは実際のエラーを1つずつ見ていくよ。まずは一番よく出会う「ModuleNotFoundError」から!

ModuleNotFoundError「No module named ‘xxx’」とは?原因と直し方

まずはこの記事の目玉テーマのひとつ、ModuleNotFoundError: No module named ‘xxx’というエラーから見ていきます。pandasやrequestsなど、外部のライブラリをimportしようとしたときに一番よく出会うエラーです。

ModuleNotFoundErrorが出る仕組み(モジュール検索の流れをざっくり)

pythonはimport ライブラリ名と書かれると、そのライブラリを決まった順番で探しに行きます。この「探しに行く場所のリスト」のことをsys.pathと呼びます。sys.pathに登録されているフォルダの中に目的のライブラリが見つからないと、pythonは「そんな名前のモジュールは知りません」という意味でModuleNotFoundErrorを返します。

実際にsys.pathの中身を確認するには、以下のようなコードで一覧表示できます。


# sys.pathの中身を1行ずつ確認するコード
import sys

for path in sys.path:
    print(path)


# 実行結果のイメージ(環境によって内容は変わります)
C:Usersユーザー名AppDataLocalProgramsPythonPython312python312.zip
C:Usersユーザー名AppDataLocalProgramsPythonPython312DLLs
C:Usersユーザー名AppDataLocalProgramsPythonPython312Lib
C:Usersユーザー名AppDataLocalProgramsPythonPython312
C:Usersユーザー名AppDataLocalProgramsPythonPython312Libsite-packages

実行すると、pythonがライブラリを探しに行くフォルダの一覧が上から順に表示されます。この中に目的のライブラリのフォルダが無いと、ModuleNotFoundErrorになります。

ここに表示されたフォルダの中に目的のライブラリが存在しなければ、当然importできません。「インストールしたはずのライブラリがsys.pathの中にあるフォルダに入っているか」が、ModuleNotFoundErrorを解決する際の基本の視点になります。

pip installしたのにimportできない・インポートエラーになる理由

pip installとimportは、似ているようで実は別々のコマンドです。pip installはライブラリを「手元に用意する」作業、importはそれを「今動かしているpythonから読み込む」作業という役割の違いがあります。この2つが噛み合っていないと、pip installは成功したように見えるのに、いざimportするとModuleNotFoundErrorになる、という現象が起こります。

例えば、requestsをpip installしたつもりでも、実際には以下のようなTracebackが出てimportできないことがあります。


Traceback (most recent call last):
  File "sample.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

requestsライブラリがまだインストールされていない(またはpythonが探しに行く場所に無い)ときに、実際にこのようなTracebackが表示されます。

この「成功したはずなのになぜ」の代表的な原因は、大きく分けて2つです。ひとつは、この後説明するライブラリのインストール名とインポート名が違うケース、もうひとつは、後半で扱う複数のpython・pip環境が混在していて、pip installした先とimportしようとしているpythonが別物になっているケースです。

Q. python -m pip install と、ただの pip install は何が違うの?

A. pip install ○○はパソコンの中にある「どれか」のpipを使ってインストールしますが、python -m pip install ○○は「今実行しているpythonに紐づくpip」を明示的に使う書き方です。複数のpython環境がある場合は、後者のほうが「どのpythonにインストールされたか」が分かりやすく、事故が起きにくくなります。

インストール名とインポート名が違うケース(beautifulsoup4→bs4など)

ライブラリの中には、pip installするときの名前と、importするときの名前が違うものがあります。代表例が、HTML解析でよく使われるBeautiful Soupです。


pip install beautifulsoup4


# インストール名は「beautifulsoup4」だが、インポートするときの名前は「bs4」
from bs4 import BeautifulSoup

このように、pip installで指定する名前と、importで指定する名前が異なるライブラリがあります。エラーが出たときは、pip install時の名前ではなく、import文に書かれているモジュール名で検索するのがコツです。

このように、インストール名とインポート名が一致しないライブラリは意外と多くあります。ModuleNotFoundErrorが出たら、まずはエラー文に表示されたモジュール名でそのまま検索してみるのがコツです。「’bs4′ というモジュール名で検索すると、実は beautifulsoup4 というライブラリ名でインストールする」という情報にたどり着けます。

中の人

え、名前が違うことなんてあるの!?って私も最初びっくりしたなぁ……知らないと絶対ハマるやつだよね。

pandas・requestsなど具体ライブラリでのModuleNotFoundError例

データ分析でよく使われるpandasや、Web上のデータ取得に使われるrequestsも、ModuleNotFoundErrorに遭遇しやすい代表的なライブラリです。


Traceback (most recent call last):
  File "sample.py", line 1, in <module>
    import pandas
ModuleNotFoundError: No module named 'pandas'


pip install pandas


Traceback (most recent call last):
  File "sample.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'


pip install requests

どちらも、エラー文に表示された名前(pandas・requests)をそのままpip installに指定すればインポートできるようになります。

どちらも直し方の基本は同じで、「今importしようとしているpythonに対して、正しくpip installできているか」を確認することに尽きます。次の章で扱うpipコマンド自体が認識されない問題や、その後の複数環境の混在が根っこの原因になっているケースが非常に多いので、続けて見ていきましょう。

中の人

次は「pipが動かない」系のエラー。これも初心者あるあるだよ〜。

pip installが「認識されない」・pip/pythonコマンドが見つからないときの対処法

ここからは、もうひとつの目玉テーマである「pipコマンドそのものが動かない」問題を扱います。

「’pip’ は内部コマンドまたは外部コマンドとして認識されていません」の意味

コマンドプロンプトにpip install ○○と入力したときに、次のようなメッセージが表示されることがあります。


C:Usersユーザー名>pip install requests
'pip' は内部コマンドまたは外部コマンドとして認識されていません。
操作可能なプログラムまたはバッチ ファイルとして指定してください。

pipコマンドの場所がPATH(環境変数)に登録されていないと、コマンドプロンプトはこのように「pipという命令を知りません」というエラーを返します。

結論から言うと、これはPATH(環境変数)が通っていないために起きています。Windowsは、コマンドを入力されたときに「PATH」というリストに登録されたフォルダの中だけを探して、該当する実行ファイルを見つけようとします。pipの実行ファイルがある場所がこのPATHに登録されていないと、「そんなコマンドは知りません」という意味でこのエラーが返ってきます。

PATH(環境変数)が通っていないときの確認・対処法

PATHが通っているかどうかは、コマンドプロンプトから確認できます。また、PATHの設定を直接いじらなくても、python -m pipという書き方をすることで回避できる場合があります。


REM 現在登録されているPATH(環境変数)の中身を確認する
echo %PATH%


REM pipコマンドが認識されない場合の回避策
REM 「python -m」を付けると、PATHが通っていなくてもpipを呼び出せる
python -m pip install requests

echo %PATH%の結果にpythonやScriptsフォルダのパスが含まれていない場合、pipコマンドが認識されません。その場合はpython -m pip installを使うと、PATHの設定を直さなくてもインストールできます。

PATHの設定を変更した直後は、開いたままのコマンドプロンプトやVS Codeのターミナルには反映されません。設定変更後は一度ウィンドウを閉じて、新しく開き直してから確認しましょう。

python/python3/pip/pip3/pyコマンドの使い分けが分からないときの整理

Windows環境では、python・python3・pip・pip3・pyと似たコマンドがいくつも出てきて、どれを打てばいいのか迷いがちです。まずはそれぞれのバージョンを確認するところから始めると、状況を整理しやすくなります。


python --version
REM 「python」コマンドで起動するpythonのバージョンを確認する

python3 --version
REM 「python3」コマンドで起動するpythonのバージョンを確認する(Windowsでは未登録のことも多い)

py --version
REM Windowsのランチャー「py」経由で起動するpythonのバージョンを確認する

pip --version
REM 「pip」コマンドが使うpython・インストール先を確認する

pip3 --version
REM 「pip3」コマンドが使うpython・インストール先を確認する

複数のコマンドが同じpythonを指しているとは限らないため、それぞれを打って中身を見比べることで、今どの環境を使っているかを把握できます。

結論として、Windowsでは基本的にpythonとpip、あるいはpyランチャーを使えば十分なケースがほとんどです。python3・pip3は主にMac/Linux環境での呼び分けの名残なので、Windowsで両方が存在して混乱している場合は、後述する「複数環境の整理」のパートも合わせて確認してみてください。

Windows/Macでのコマンドの違い(Macは軽く触れる程度)

この記事は基本的にWindows(コマンドプロンプト)を前提に説明していますが、Macを使っている場合は、標準でpythonコマンドがpython3を指していないことがあり、python3・pip3を明示的に使う場面が多くなります。Macのターミナルで同じ手順を試す場合は、まずpython3 --versionのように「3」を付けたコマンドで試してみると、Windowsとの違いに惑わされにくくなります。

中の人

ここからがこの記事のメインディッシュ!実はさっきまでのエラー、根っこの原因が同じだったりするんだよね。

複数のpython/pip環境が混在して「今どれを使っているか」分からなくなったときの整理法

ModuleNotFoundErrorやpipが認識されない問題の根っこには、実は「今操作しているpython・pipが、自分が思っているものと違う」という複数バージョンのpython・pip環境の混在が隠れていることが少なくありません。ここでは、その整理の仕方を見ていきます。

グローバル環境とvenv(仮想環境)の違いをざっくり理解する

パソコン全体で共通して使われるpythonの環境を「グローバル環境」、プロジェクトごとに独立して作る専用の環境を「venv(仮想環境)」と呼びます。グローバル環境にどんどんライブラリをインストールしていくと、プロジェクトごとに必要なライブラリのバージョンが違う場合に競合してしまうことがあります。venvは、プロジェクトごとに専用の「箱」を作って、その中だけでライブラリを管理する仕組みだとイメージすると分かりやすいです。

この「箱」を切り替え忘れる、あるいはそもそも箱を作らずに毎回グローバル環境で作業してしまう、といったことが、複数環境が混在してしまう主な原因です。仮想環境の使い方に一度慣れてしまえば、プロジェクトを始めるたびに「まずvenvを作って有効化する」が自然な習慣になり、混在を防ぎやすくなります。

今使っているpython/pipがどれか確認する方法

「今使っているpython・pipがどこにあるものか」は、以下のコマンドで確認できます。


REM 今使われているpythonコマンドの実体(場所)を確認する
where python

REM 今使われているpipコマンドの実体(場所)を確認する
where pip


# 実行中のスクリプトが、どのpython.exeで動いているかを確認するコード
import sys

print(sys.executable)

where python・where pipはコマンドプロンプトから見えているpythonの場所、sys.executableはスクリプトを実際に実行しているpythonの場所を表示します。この2つが食い違っている場合、複数環境の混在が疑われます。

表示されたパスにvenvという文字列が含まれていれば仮想環境内のpythonを、含まれていなければグローバル環境のpythonを使っていることが分かります。

VS Codeのpythonインタープリター選択ができない・合っているか分からないとき

Atom時代はコマンドプロンプトから直接コードを実行していましたが、VS Codeに移行してからは内蔵ターミナルを使う流れに変わりました。VS Codeの導入がまだの方は、コードの記述も参考にしてください。

VS Codeでは、画面右下(またはコマンドパレット)から「どのpythonを使ってコードを実行するか」を選択できます。この選択が、実際にライブラリをインストールしたpythonと違っていると、「pip installでは成功したのにVS Code上のimportではModuleNotFoundErrorになる」という状態が起こります。プロジェクトフォルダに.vscode/settings.jsonを作成して、使いたいpythonのパスを明示しておくと、この選択ミスを防ぎやすくなります。


{
    "python.defaultInterpreterPath": "C:\Users\ユーザー名\Projects\my_project\venv\Scripts\python.exe"
}

プロジェクト直下の.vscodeフォルダにこのsettings.jsonを置くと、VS Codeがこのプロジェクトを開いたときに使うpythonインタープリターを明示的に指定できます。パスは自分の環境の実際のpython.exeの場所に置き換えてください。

venvを有効化し忘れていたときのサインと確認方法

venvは「作る」だけでなく「有効化(activate)する」操作を毎回行わないと、実際にはグローバル環境で作業してしまいます。有効化できているかどうかは、コマンドプロンプトの表示で見分けられます。


venvScriptsactivate

Macの場合は1行だけコマンドが異なります(source venv/bin/activate)。


REM 有効化する前のコマンドプロンプトの表示
C:Usersユーザー名my_project>

REM venvScriptsactivate を実行した後の表示
(venv) C:Usersユーザー名my_project>

venvを有効化すると、行の先頭に(venv)という表示が付きます。この表示が無い場合は、仮想環境が有効化されていない状態でコマンドを実行していることになります。

venvを有効化し忘れたままpip installすると、せっかく作った仮想環境ではなくグローバル環境にライブラリがインストールされてしまいます。プロンプトの先頭に(venv)のような表示が出ているかどうかを、作業を始める前に必ず確認する習慣をつけましょう。

Q. venvを有効化し忘れると、具体的に何が困るの?

A. 有効化を忘れたままライブラリをグローバル環境にインストールしてしまうと、プロジェクトごとにライブラリのバージョンを分けて管理するというvenv本来のメリットが失われます。さらに、後から「あれ、このライブラリはどの環境に入れたんだっけ」と分からなくなり、まさに次の章で扱う「複数環境の混在」状態を自ら作り出してしまうことになります。

中の人

もし「自分の環境が今どうなってるか、もう全然わからない……」ってなってても大丈夫。順番に整理していこうね。

すでに環境がぐちゃぐちゃに混在してしまった状態からの復旧手順

ここまでは「そもそも環境が混在しないようにする」予防の話が中心でしたが、この章では一歩進んで、すでに複数のpython・pip環境が混在してしまい、何をどうすればいいか分からなくなった状態からの復旧を扱います。多くの解説記事は「最初からvenvを使いましょう」という予防目線で終わってしまいますが、この記事では「今まさに詰まっている人」がどう抜け出すかにも焦点を当てます。

まずは、以下の項目に当てはまるかどうかをチェックしてみてください。

pip installしたはずのライブラリが、importすると見つからないと言われる
where pythonを実行すると、複数のpythonのパスが表示される
venvを作った記憶はあるが、今それを使っているのかどうか分からない
VS Codeで動くのにコマンドプロンプトからは動かない(またはその逆)ことがある

1つでも当てはまれば、次のステップで状態を整理していきましょう。

今の状態を確認する(棚卸しステップ)

まずは今の状態を正確に把握することから始めます。以下のコマンドで、今使っているpython・pipの場所と、インストール済みのライブラリを確認しましょう。


REM 今インストールされているライブラリの一覧を、見やすい表形式で確認する
pip list

REM 今インストールされているライブラリの一覧を、requirements.txtに書ける形式で確認する
pip freeze

REM 今使われているpython本体のバージョンを確認する
python --version

REM 今使われているpythonコマンドの実体(場所)を確認する
where python

これらを順番に実行することで、「今の環境に何が入っていて、どのpythonを使っているか」を棚卸しできます。復旧作業に入る前に、まずこの現状把握から始めます。

ここで表示された内容をメモしておくと、この後どのライブラリを再インストールすればいいかが分かりやすくなります。

仮想環境を作り直してクリーンな状態に戻すステップ

状態の把握ができたら、思い切って新しいvenvを作り直すのが、遠回りに見えて実は一番確実な方法です。以下の流れで、クリーンな状態から作り直します。


REM 1. 新しい仮想環境を作る(venvという名前のフォルダが作成される)
python -m venv venv

REM 2. 作った仮想環境を有効化する
venvScriptsactivate

REM 3. 必要なライブラリをまとめてインストールする(requirements.txtがある場合)
pip install -r requirements.txt

requirements.txtが無い場合は、pip install pandasのように、必要なライブラリを1つずつ個別にインストールしていきます。

古いvenvフォルダを削除する前に、そのプロジェクトで使っていたライブラリの一覧(pip freezeの結果など)を必ず控えておきましょう。控えないまま削除してしまうと、後で「何をインストールしていたか」が分からなくなってしまいます。既存のプロジェクトフォルダでいきなり試すのではなく、まずは練習用の空フォルダで一連の流れを試しておくと安心です。

「とりあえずこれをやれば大体直る」応急処置フロー

「原因を細かく特定している時間がない」というときのために、判断に迷ったときの大まかな流れをまとめておきます。

大まかには、「エラー文をそのまま確認する」→「今使っているpython・pipの場所を確認する」→「PATHとvenvの有効化を確認する」→「それでも直らなければ仮想環境を作り直す」という順番で進めると、多くのケースで解決に近づけます。

中の人

ここからは番外編!基本のエラーをサクサク紹介していくよ。

これも知っておきたい、python初心者がよくつまずく基本エラー8選

※ここで紹介する基本エラーについては、それぞれ別記事で詳しく深掘りする予定です。ここでは「どんなエラーか」「なぜ起きるか」「どう直すか」を1行ずつ、テンポよく紹介します。

SyntaxError(構文エラー)

文法そのものが間違っているときに出るエラーです。多くはコロン:の付け忘れやカッコの閉じ忘れが原因なので、エラーが出た行とその前の行を見比べてみましょう。


print("Hello


SyntaxError: unterminated string literal (detected at line 1)

IndentationError(インデントエラー)

コードの字下げ(インデント)がそろっていないときに出るエラーです。半角スペースとタブが混在している場合にも起きやすいので、エディタのインデント設定を統一しましょう。


if True:
    print("OK")
      print("インデントがずれている")


IndentationError: unexpected indent

NameError(名前が定義されていない)

定義していない変数や関数名を使おうとしたときに出るエラーです。スペルミスや、変数を定義する前に使ってしまっていないかを確認しましょう。


print(mei)


NameError: name 'mei' is not defined

TypeError(型が違う)

文字列と数値のように、異なる型同士を組み合わせて演算しようとしたときに出るエラーです。str()やint()で型を変換してから処理しましょう。


print("年齢は" + 20)


TypeError: can only concatenate str (not "int") to str

ValueError(値が不正)

型自体は正しいものの、値の中身が処理にふさわしくないときに出るエラーです。数値に変換できない文字列をint()に渡した場合などが代表例で、渡す値の中身を見直しましょう。


int("abc")


ValueError: invalid literal for int() with base 10: 'abc'

IndexError(範囲外アクセス)

リストなどの要素数を超えた番号(インデックス)にアクセスしようとしたときに出るエラーです。要素数をlen()で確認してからアクセスすると安全です。


kudamono = ["りんご", "みかん"]
print(kudamono[5])


IndexError: list index out of range

KeyError(存在しないキー)

辞書(dict)に存在しないキーを指定したときに出るエラーです。inで存在確認をするか、.get()メソッドを使うと安全に扱えます。


puroffiru = {"namae": "ユージン"}
print(puroffiru["nenrei"])


KeyError: 'nenrei'

AttributeError(属性が存在しない)

そのオブジェクトが持っていないメソッドやプロパティを呼び出そうとしたときに出るエラーです。変数の中身が思っている型と違っていないか、type()で確認してみましょう。


mojiretsu = "こんにちは"
mojiretsu.append("!")


AttributeError: 'str' object has no attribute 'append'

豆知識、知っておくと安心なエラーの話

Q. ZeroDivisionErrorって何?

A. ある数値を0で割ろうとしたときに出るエラーです。数学的に0で割ることはできないため、pythonがエラーとして教えてくれます。ユーザーの入力値を使って割り算をするプログラムでは、事前に0でないかを確認しておくと安心です。


print(1 / 0)


ZeroDivisionError: division by zero

Q. ImportErrorとModuleNotFoundErrorは何が違うの?

A. どちらもimportに関するエラーですが、ModuleNotFoundErrorは「そのモジュール自体が見つからない」場合に、ImportErrorは「モジュールは見つかったが、その中の特定の関数やクラスを読み込めない」場合に出ます。実はModuleNotFoundErrorはImportErrorの一種(サブクラス)として用意されているエラーで、「モジュールごと見つからないのか」「モジュールの中身の一部が見つからないのか」という粒度の違いだと考えると整理しやすくなります。