ImportError: No Module Named mysql.connector

When working in Python you may encounter the the error ImportError: No Module Named mysql.connector when attempting to use the MySQL Connector Python Module.

If this error occurs, it typically means that the mysql-connector-python package which provides a connection for MySQL database from Python, is not installed in your current environment.

In this tutorial, we will cover some basic steps that you can use to fix this error in your Python environment. Keep in mind that we assume you are using Python 3.

Install the MySQL Connector Python Package

The first step is to ensure you have the msql-python-connector package installed on your environment. You can do this by using pip, which is a package manager for Python.

Open a terminal (command prompt in Windows) and run the command:

pip install mysql-connector-python

Output:

Defaulting to user installation because normal site-packages is not writeable
Collecting mysql-connector-python
  Downloading mysql_connector_python-8.0.33-cp310-cp310-manylinux1_x86_64.whl (27.4 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 27.4/27.4 MB 4.0 MB/s eta 0:00:00
Requirement already satisfied: protobuf<=3.20.3,>=3.11.0 in (from mysql-connector-python) (3.20.3)
Installing collected packages: mysql-connector-python
Successfully installed mysql-connector-python-8.0.33

This will install the MySQL connector for Python. If you’re using a specific version of Python 3, you might need to use pip3 instead of pip

pip3 install mysql-connector-python

NOTE: If you are on a Python virtual environment, be sure to activate your environment before running this command to ensure that the package is installed in the current environment rather than global scope.

Verify Installation

Once the install is complete, you should verify if the MySQL Connector Python has been installed successfully.

You can do this by running the following command in your Python environment:

>>> import mysql.connector
>>>

If you don’t get any error messages, that means the package has been installed successfully.

Other Causes

If you’re still getting the same error after running the installation, there might be some other issues.

The following are some potential causes you can verify.

Python or Pip Version

Ensure you are using the correct version of Python and pip. You might have multiple versions installed on your machine, so you need to ensure that you’re installing the package for the correct version.

Virtual Environments

If you’re using a Python virtual environment, you need to make sure you’ve activated it before installing the package. Also, run the import statement within the same environment where the package was installed.

PATH variable

Ensure the Python and pip directories are added to your system’s PATH variable.

Permissions

You might need administrative permissions to install the package. If so, you can use the sudo command (on Linux or macOS) or run the command prompt as an administrator (on Windows).

Last Resort - Alternative Driver

If the problem still persists, you may consider using an alternative MySQL driver, such as PyMySQL, a pure-Python MySQL client library, and can be used as a drop-in replacement for MySQL Connector.

You can install it via pip:

pip install PyMySQL

To connect to your target MySQL version, run the code as shown:

import pymysql

conn = pymysql.connect(
    host='localhost',
    user='root',
    password='mysql',
    db='db',
    charset='utf8mb4',
    cursorclass=pymysql.cursors.DictCursor
)

Conclusion

In this tutorial, we discussed the measures you can take to fix the “ImportError: No Module Named mysql.connector” error when working in Python.