Pythonで「No module named mysql」エラーが出る原因と解決方法【Windows環境の完全ガイド】
PythonでMySQLデータベースに接続するスクリプトを実行した際に、「No module named mysql」というエラーが表示されて困った経験はないだろうか。特にWindows環境では、MySQL関連のパッケージが正しくインストールされていない、あるいは使用しているPython環境と異なる場所にインストールされていることが原因でこのエラーが発生するケースが多い。
この記事では、「No module named mysql」エラーの原因から具体的な解決方法までをわかりやすく解説する。Python初心者から実務でMySQLを扱うエンジニアまで、トラブルシューティングの決定版として役立つ内容をまとめた。
「No module named mysql」エラーとは何か
PythonでMySQLデータベースに接続する場合、通常は専用のコネクタライブラリを使用する。しかしPython標準ライブラリにはMySQL接続機能が含まれていないため、外部パッケージをインストールする必要がある。
「No module named mysql」というエラーは、PythonがMySQL関連のライブラリを見つけられない場合に発生するエラーだ。つまり、現在実行しているPython環境にMySQLコネクタが存在しないことを意味している。
特にWindowsでは、複数のPythonバージョンがインストールされているケースが多く、別のPython環境にパッケージを入れてしまうことでこの問題が起きやすい。
まず確認すべきPythonの実行環境
最初に確認すべきなのは、実際にスクリプトがどのPythonを使用して実行されているかという点である。
Windowsでは複数のPythonが共存していることが珍しくない。たとえば以下のような環境が同時に存在することもある。
・Python公式インストーラ版
・Microsoft Store版Python
・Anaconda
・仮想環境（venv）
そのため、パッケージをインストールしたPythonと、スクリプトを実行しているPythonが異なるとモジュールが見つからない状態になる。
コマンドプロンプトでPythonのバージョンや場所を確認すると、どのPythonが実行されているのかを把握できる。ここで表示されたPython環境に対してMySQLパッケージをインストールする必要がある。
MySQLコネクタをインストールする方法
PythonからMySQLに接続するための最も一般的で安定したパッケージは「mysql-connector-python」である。
このパッケージをインストールすることで、PythonスクリプトからMySQLデータベースに接続できるようになる。
Windows環境では通常、pipを使ってインストールする。もしpipコマンドが認識されない場合でも、Pythonモジュールとしてpipを呼び出せば問題なくインストール可能だ。
また、Pythonが複数インストールされている場合は、pyコマンドを使ってインストールすることで正しいPython環境にパッケージを導入できる。
インストール後の動作確認
パッケージのインストールが完了したら、正常に導入されているか確認することが重要だ。
Python環境でMySQLコネクタをインポートできるかをテストすることで、エラーの原因が解消されたかどうかを簡単に確認できる。
問題なくインポートできれば、PythonからMySQLへ接続する準備は整っている。
よくある原因1：間違った環境にインストールしている
このエラーで最も多い原因は、パッケージを別のPython環境にインストールしてしまうケースである。
例えば次のような開発環境を使っている場合は特に注意が必要だ。
・VS Code
・PyCharm
・仮想環境（venv）
・Anaconda
これらの環境では、IDEが独自のPython環境を使用していることがある。そのため、グローバルPythonにパッケージをインストールしてもIDE内では認識されないことがある。
仮想環境を使用している場合は、環境をアクティベートしてからパッケージをインストールする必要がある。
よくある原因2：import文が間違っている
意外と見落とされがちなのが、import文の書き方のミスである。
mysql-connector-pythonを使用する場合、正しいインポート方法は次の形式になる。
import mysql.connector
もしスクリプト内で「import mysql」とだけ書いていると、Pythonはその名前のモジュールを見つけることができずエラーが発生する。
この違いは小さいが、エラーの原因として非常に多いポイントなので確認しておきたい。
mysql-connector以外のMySQLライブラリ
PythonでMySQLを扱うためのライブラリはmysql-connectorだけではない。用途や開発環境によっては別のライブラリを使うケースもある。
代表的なものには次のようなものがある。
・PyMySQL
・mysqlclient
これらのライブラリを使用する場合は、それぞれ対応するパッケージをインストールし、適切なimport文を使用する必要がある。
例えばPyMySQLの場合は「pymysql」をインポートし、mysqlclientの場合は「MySQLdb」を使用する。
WindowsでMySQL接続トラブルを防ぐベストプラクティス
PythonとMySQLを安定して運用するためには、開発環境を整理することが重要である。
まず、プロジェクトごとに仮想環境を作成し、その環境内に必要なパッケージをインストールする習慣をつけるとトラブルが減る。また、IDEのPythonインタプリタ設定を確認して、どのPythonが使用されているか常に把握しておくことも重要だ。
さらに、パッケージのインストール状況を定期的に確認することで、環境の不整合を防ぐことができる。
まとめ
Pythonで「No module named mysql」というエラーが発生する原因のほとんどは、MySQLコネクタがインストールされていない、または使用しているPython環境と異なる場所にインストールされていることにある。
解決のポイントは以下の通りだ。
・実行しているPython環境を確認する
・mysql-connector-pythonをインストールする
・正しいimport文を使用する
・仮想環境を使っている場合は環境内でインストールする
これらを順番に確認することで、ほとんどのケースでエラーを解消できる。PythonとMySQLの連携はデータ処理やWeb開発で非常に重要な技術の一つだ。環境トラブルを素早く解決し、安定した開発環境を整えていこう。
