Introduction

If you search for MySQLdb on Python projects, the confusing part is that the import name and the package name are not always the same. In modern Python environments, the package you usually install with pip is mysqlclient, while the code still imports as MySQLdb.

Understand the Package Name

Older tutorials often say:

pip install MySQLdb

That usually fails, because MySQLdb is the historical module name, not the package most users install today. The common replacement is:

pip install mysqlclient

After installation, the import still looks like this:

import MySQLdb

That mismatch is the main source of confusion. The installation command and the import statement do not use the same name.

Install the Native Dependencies

mysqlclient is a compiled extension, so pip alone is sometimes not enough. The Python package also needs MySQL or MariaDB client headers and a compiler toolchain.

Typical Linux setup looks like this:

sudo apt-get update
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential
pip install mysqlclient

On Red Hat style systems, the package names differ, but the idea is the same: install Python development headers plus MySQL client development libraries first.

On macOS with Homebrew, a common flow is:

brew install mysql pkg-config
pip install mysqlclient

Windows is often the hardest environment because prebuilt wheels may not exist for every Python version. If mysqlclient fails to build there, many teams choose a pure Python alternative such as PyMySQL, or they pin to a Python version with available wheels.

Verify the Installation

After installation, check that Python can import the driver:

python -c "import MySQLdb; print('MySQLdb import worked')"

If the command succeeds, the package is installed correctly enough for Python to load it. At that point, test an actual connection to catch client-library mismatches early.

1import MySQLdb
2
3connection = MySQLdb.connect(
4    host="127.0.0.1",
5    user="app_user",
6    passwd="secret",
7    db="sample_db",
8)
9
10cursor = connection.cursor()
11cursor.execute("SELECT VERSION()")
12print(cursor.fetchone())
13
14cursor.close()
15connection.close()

This small connection test is more useful than a version check alone, because it confirms the driver can talk to the installed database client libraries.

When to Use Alternatives

If your environment makes native builds painful, consider whether you actually need MySQLdb compatibility. Two common alternatives are:

• 'PyMySQL, which is pure Python and easier to install'
• 'mysql-connector-python, which comes from Oracle and has its own API style'

The tradeoff is ecosystem compatibility. Some older codebases or frameworks explicitly expect MySQLdb, in which case mysqlclient remains the closest match.

Troubleshooting Build Failures

Most installation failures come from one of three causes:

• missing C compiler
• missing MySQL client development headers
• using the wrong Python environment or pip

If pip install mysqlclient fails, read the compiler error carefully instead of retrying blindly. The fix is usually outside Python itself. For example, if a header file cannot be found, installing system packages is the real solution.

Also confirm that pip and python point to the same interpreter:

python -m pip install mysqlclient

That avoids installing the package into one environment and running your code in another.

Common Pitfalls

• Installing MySQLdb directly with pip and expecting the package name to match the import name.
• Forgetting the native MySQL client development libraries required by mysqlclient.
• Using pip from a different virtual environment than the one that runs the application.
• Assuming an import test is enough without checking a real database connection.
• Fighting Windows build errors for too long when a compatible pure Python driver would meet the requirement more cleanly.

Summary

• The modern pip package is usually mysqlclient, even though the import name is MySQLdb.
• Native dependencies matter because mysqlclient is a compiled extension.
• Use python -m pip install mysqlclient to target the correct interpreter.
• Verify installation with both an import test and a real database connection.
• Consider PyMySQL or another driver if native builds are a poor fit for the environment.