Practice Now
Python
ImportError
MySQL
ModuleNotFoundError
Troubleshooting

ImportError No module named 'MySQL'

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design
DatabasesPythonDebugging & Errors

Introduction

The error ImportError: No module named 'MySQL' (or ModuleNotFoundError: No module named 'mysql') means Python cannot find a MySQL connector package. This happens because mysql is not a standard library module — you need to install a third-party package. The three main options are mysqlclient (C-based, fastest), PyMySQL (pure Python, easiest to install), and mysql-connector-python (Oracle's official connector). The choice depends on your project's needs and environment constraints.

The Error

python
1import mysql.connector
2# ModuleNotFoundError: No module named 'mysql'
3
4import MySQLdb
5# ModuleNotFoundError: No module named 'MySQLdb'
6
7import pymysql
8# ModuleNotFoundError: No module named 'pymysql'

Each import corresponds to a different package that must be installed separately.

mysqlclient is a C extension wrapper around libmysqlclient. It is the fastest option and is the default Django MySQL backend:

bash
1# Install system dependencies first
2# Ubuntu/Debian
3sudo apt-get install python3-dev default-libmysqlclient-dev build-essential
4
5# macOS
6brew install mysql pkg-config
7
8# CentOS/RHEL
9sudo yum install python3-devel mysql-devel
10
11# Then install the Python package
12pip install mysqlclient
python
1import MySQLdb
2
3connection = MySQLdb.connect(
4    host='localhost',
5    user='root',
6    passwd='password',
7    db='mydb'
8)
9cursor = connection.cursor()
10cursor.execute('SELECT * FROM users')
11rows = cursor.fetchall()
12connection.close()

Fix 2: Install PyMySQL (Easiest, Pure Python)

No system dependencies needed — works everywhere Python runs:

bash
pip install pymysql
python
1import pymysql
2
3connection = pymysql.connect(
4    host='localhost',
5    user='root',
6    password='password',
7    database='mydb',
8    cursorclass=pymysql.cursors.DictCursor
9)
10
11with connection:
12    with connection.cursor() as cursor:
13        cursor.execute('SELECT * FROM users WHERE id = %s', (1,))
14        user = cursor.fetchone()
15        print(user)  # {'id': 1, 'name': 'Alice', 'email': '[email protected]'}

Using PyMySQL as MySQLdb Drop-in

If your code or framework expects MySQLdb (like Django), PyMySQL can masquerade as it:

python
1# Add to the top of your settings.py or manage.py
2import pymysql
3pymysql.install_as_MySQLdb()
4
5# Now import MySQLdb works
6import MySQLdb  # Actually uses PyMySQL

Fix 3: Install mysql-connector-python (Oracle Official)

bash
pip install mysql-connector-python
python
1import mysql.connector
2
3connection = mysql.connector.connect(
4    host='localhost',
5    user='root',
6    password='password',
7    database='mydb'
8)
9
10cursor = connection.cursor(dictionary=True)
11cursor.execute('SELECT * FROM users')
12users = cursor.fetchall()
13cursor.close()
14connection.close()

Comparison

PackageImportSpeedDependenciesDjango Support
mysqlclientimport MySQLdbFastest (C)Needs system libsDefault backend
PyMySQLimport pymysqlSlower (pure Python)NoneVia install_as_MySQLdb()
mysql-connector-pythonimport mysql.connectorMediumNoneNeeds third-party backend

Django Configuration

python
1# settings.py — with mysqlclient (default)
2DATABASES = {
3    'default': {
4        'ENGINE': 'django.db.backends.mysql',
5        'NAME': 'mydb',
6        'USER': 'root',
7        'PASSWORD': 'password',
8        'HOST': 'localhost',
9        'PORT': '3306',
10    }
11}
12
13# With PyMySQL — add to manage.py or settings.py
14import pymysql
15pymysql.install_as_MySQLdb()

SQLAlchemy Configuration

python
1from sqlalchemy import create_engine
2
3# With mysqlclient
4engine = create_engine('mysql+mysqldb://root:password@localhost/mydb')
5
6# With PyMySQL
7engine = create_engine('mysql+pymysql://root:password@localhost/mydb')
8
9# With mysql-connector-python
10engine = create_engine('mysql+mysqlconnector://root:password@localhost/mydb')

Virtual Environment Issues

bash
1# Check if installed in the right environment
2pip list | grep -i mysql
3
4# If using venv, make sure it's activated
5source venv/bin/activate
6pip install pymysql
7
8# If using conda
9conda install -c conda-forge pymysql
10
11# Verify
12python -c "import pymysql; print(pymysql.__version__)"

Common Pitfalls

  • Installing mysql instead of mysql-connector-python: pip install mysql installs a deprecated, abandoned package (last updated 2013). Use pip install mysql-connector-python for Oracle's connector, or pip install pymysql for the pure Python option.
  • Missing system dependencies for mysqlclient: mysqlclient requires libmysqlclient-dev (Linux) or mysql (macOS Homebrew). Without these, pip install mysqlclient fails with a compilation error. Use PyMySQL if you cannot install system packages.
  • Wrong Python/pip version: Running pip install pymysql may install to Python 2 while your project uses Python 3. Use pip3 install pymysql or python -m pip install pymysql to target the correct interpreter.
  • Confusing import names: mysqlclient is imported as MySQLdb, mysql-connector-python is imported as mysql.connector, and PyMySQL is imported as pymysql. The package name and import name are different for each.
  • Conflicting packages: Installing both mysql-connector-python and mysql-connector-python-rf creates import conflicts. Only one mysql.connector package should be installed at a time.

Summary

  • Install pymysql for the easiest setup (no system dependencies, pure Python)
  • Install mysqlclient for best performance and Django's default MySQL backend
  • Use pymysql.install_as_MySQLdb() to use PyMySQL as a drop-in for MySQLdb
  • Match the SQLAlchemy connection string dialect to the installed package (mysql+pymysql, mysql+mysqldb)
  • Always verify the package is installed in the correct virtual environment with pip list
Related reading
Course
Beginner
27 lessons
10 hours
System Design Fundamentals

Build a strong foundation in designing scalable, reliable distributed systems.

View the course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design
Codemia
© 2026 Codemia
Resources
Legal
Social
All Rights Reserved.