Registry / database / mysqlclient

mysqlclient

JSON →
library2.2.8pypypiunverified

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.

database
pip install mysqlclient
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
musl
py 3.103.925 runs
build_error
glibc
py 3.103.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.
fix
Before 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.
fix
Ensure `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.
fix
Update 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.
fix
Use `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.
fix
Ensure 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.
fix
Avoid 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.
fix
If 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
Upgrade
Version history
2.2.8latest on PyPI
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.
Agent activity
20 hits · last 30 days
node
8
seranking-bot
4
Amazon
2
ahrefsbot
2
Meta
1
bingbot
1
bytedance
1
Resources