mysqlclient is a Python interface to MySQL that acts as a fork of MySQLdb1, providing Python 3 support and numerous bug fixes. It is a C extension that wraps the official MySQL C API (libmysqlclient), offering superior performance compared to pure-Python drivers. The library currently operates at version 2.2.8 and maintains a healthy release cadence, with at least one new version released in the past three months.
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
build_error
glibcpy 3.10–3.925 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MySQLdb
✓ import MySQLdb
✗ import _mysql
MySQLdb is the higher-level, DB API-compliant module. _mysql is a lower-level, non-portable module that directly wraps the MySQL C API and should generally be avoided for application development.
connect
✓ from MySQLdb import connect
This quickstart demonstrates how to establish a connection to a MySQL database, execute a simple query, create a table, insert data, and retrieve data using `mysqlclient`. Connection parameters are loaded from environment variables for flexibility. Remember to replace placeholder credentials with actual, securely managed values in a production environment.
import MySQLdb
import os
DB_HOST = os.environ.get('MYSQL_HOST', '127.0.0.1')
DB_USER = os.environ.get('MYSQL_USER', 'root')
DB_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'your_password') # Replace with a secure method for production
DB_NAME = os.environ.get('MYSQL_DATABASE', 'testdb')
try:
# Establish a connection
conn = MySQLdb.connect(
host=DB_HOST,
user=DB_USER,
password=DB_PASSWORD,
database=DB_NAME
)
cursor = conn.cursor()
# Execute a query
cursor.execute("SELECT VERSION();")
version = cursor.fetchone()
print(f"Database version: {version[0]}")
# Example: Create a table (if it doesn't exist)
cursor.execute("CREATE TABLE IF NOT EXISTS my_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))")
print("Table 'my_table' ensured.")
# Example: Insert data
cursor.execute("INSERT INTO my_table (name) VALUES (%s)", ("Test Name",))
conn.commit()
print("Data inserted.")
# Example: Read data
cursor.execute("SELECT id, name FROM my_table")
rows = cursor.fetchall()
for row in rows:
print(f"ID: {row[0]}, Name: {row[1]}")
finally:
# Close the cursor and connection
if 'cursor' in locals() and cursor:
cursor.close()
if 'conn' in locals() and conn:
conn.close()
print("Database connection closed.")
Debug
Known issues
breakingInstallation via `pip install mysqlclient` often fails without pre-installed system-level MySQL client development headers, a C/C++ compiler, and `pkg-config` (on POSIX systems). This is because `mysqlclient` is a C extension that needs to compile against native libraries.fixBefore installing `mysqlclient`, install the necessary system packages. For Debian/Ubuntu: `sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config`. For Red Hat/CentOS: `sudo yum install python3-devel mysql-devel pkgconfig`. For macOS: `brew install mysql pkg-config`. For Windows, ensure 'Build Tools for Visual Studio' and 'MariaDB Connector/C' are installed.
affects: All versions
breakingIn version 2.2.0, `mysqlclient` switched from using `mysql_config` to `pkg-config` for discovering compiler and linker flags during installation. If `pkg-config` is not installed or configured correctly, compilation will fail.fixEnsure `pkg-config` is installed on your system. For Debian/Ubuntu: `sudo apt-get install pkg-config`. For Red Hat/CentOS: `sudo yum install pkgconfig`.
affects: >=2.2.0
breakingThe `Cursor.executemany()` method's argument format changed in version 2.2.0. It now expects a sequence of tuples, even for single-value inserts, instead of a sequence of scalar values.fixUpdate your `executemany` calls. For example, change `executemany("INSERT INTO t (data) VALUES (%s)", [1, 2, 3])` to `executemany("INSERT INTO t (data) VALUES (%s)", [(1,), (2,), (3,)])`. affects: >=2.2.0
deprecatedThe `passwd` and `db` keyword arguments in the `MySQLdb.connect()` function are deprecated. They will be removed in future versions.fixUse `password` and `database` keyword arguments instead.
affects: >=2.1.0
gotchaAs of v2.2.8, `mysqlclient` offers experimental support for free-threaded Python (importing `MySQLdb` doesn't enable the GIL). However, the library explicitly states that it *does not* support simultaneous operations on a single `Connection` object from multiple threads concurrently. Doing so will result in undefined behavior.fixEnsure that each `Connection` object is used by only one thread at a time. If multi-threading is required, establish a separate `Connection` for each thread or use a connection pooling mechanism that manages thread-safe access.
affects: >=2.2.8
deprecatedThe `Connection.shutdown()` and `Connection.kill()` methods are deprecated, as the underlying MySQL C API functions (`mysql_shutdown()` and `mysql_kill()`) were removed in MySQL 8.3. These methods will emit a `DeprecationWarning` in future versions.fixAvoid using `Connection.shutdown()` and `Connection.kill()`. If server administration is required, use dedicated MySQL administration tools or SQL commands executed via a standard cursor.
affects: >=2.2.2 (warning will appear in future versions)
gotchaOn macOS, certain versions of `mysql-connector-c` installed via Homebrew or official packages may have incorrect default configuration options, causing `mysqlclient` compilation errors. This often manifests as linker errors related to `ssl` or `crypto` libraries.fixIf encountering compilation errors on macOS, a common workaround is to modify the `mysql_config` script (usually found in `/usr/local/bin` or a similar path). Specifically, change the `libs` definition from `libs="-L$pkglibdir" libs="$libs -l "` to `libs="-L$pkglibdir" libs="$libs -lmysqlclient -lssl -lcrypto"`.
affects: All versions on macOS with problematic `mysql-connector-c` installations
Audit
Dependencies
Python 3 Development Headersrequiredmysqlclient is a C extension and requires Python development headers for compilation. Examples: python3-dev (Debian/Ubuntu), python3-devel (Red Hat/CentOS).
MySQL Client Development Headers and Librariesrequiredmysqlclient links against the MySQL C API (libmysqlclient). Examples: default-libmysqlclient-dev (Debian/Ubuntu), mysql-devel (Red Hat/CentOS), mysql-connector-c (macOS).
C/C++ CompilerrequiredThe library compiles C code during installation. Examples: build-essential (Debian/Ubuntu), Development Tools (Red Hat/CentOS), Xcode Command Line Tools (macOS), Build Tools for Visual Studio (Windows).
pkg-configrequiredOn POSIX systems, mysqlclient uses pkg-config to find compiler/linker flags. It is required for successful compilation if pre-built wheels are not available.