Install & Compatibility
Where this runs
tested against v2.2.0.20260508 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MySQLdb-stubs
✓ import MySQLdb-stubs
✗ import MySQLdb-stubs
This quickstart demonstrates how to connect to a MySQL database using the `MySQLdb` module (provided by `mysqlclient`), execute a simple query, create a table, insert data, and fetch results. It includes basic error handling and uses environment variables for sensitive connection details, which is a common practice in production environments. Ensure `mysqlclient` and its system dependencies are installed before running.
import MySQLdb
import os
host = os.environ.get('MYSQL_HOST', '127.0.0.1')
user = os.environ.get('MYSQL_USER', 'root')
password = os.environ.get('MYSQL_PASSWORD', 'password')
database = os.environ.get('MYSQL_DATABASE', 'testdb')
conn = None
try:
# Establish a connection to the database
conn = MySQLdb.connect(host=host, user=user, password=password, database=database)
print("Successfully connected to MySQL database!")
# Create a cursor object
cursor = conn.cursor()
# Execute a query
cursor.execute("SELECT VERSION();")
# Fetch and print the result
result = cursor.fetchone()
print(f"MySQL Database version: {result[0]}")
# Example: Create a table (if not exists)
cursor.execute("CREATE TABLE IF NOT EXISTS example_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255));")
print("Table 'example_table' ensured to exist.")
conn.commit()
# Example: Insert data
cursor.execute("INSERT INTO example_table (name) VALUES (%s);", ("Test Name",))
print("Data inserted.")
conn.commit()
# Example: Select data
cursor.execute("SELECT id, name FROM example_table;")
rows = cursor.fetchall()
print("Data in example_table:")
for row in rows:
print(f" ID: {row[0]}, Name: {row[1]}")
except MySQLdb.Error as e:
print(f"Error connecting to or interacting with MySQL: {e}")
if conn:
conn.rollback()
finally:
if conn:
conn.close()
print("Database connection closed.")
Debug
Known issues
breakingStub versions can introduce type-checking breaking changes. While `typeshed` aims for stability, any update to `types-mysqlclient` (even a patch version) might reveal type inconsistencies in your code due to improved or corrected annotations.fixPin your `types-mysqlclient` dependency to a specific version or a specific date-based component of the version in your `requirements.txt` (e.g., `types-mysqlclient==2.2.0.20260408`) and update deliberately after testing.
affects: All versions of types-mysqlclient (especially across dates in the version string, e.g., 2.2.0.20260402 -> 2.2.0.20260408)
gotchaThe `mysqlclient` package (the runtime library) often fails to install with a 'Failed building wheel' error if necessary system-level development headers and libraries are missing. This is not an issue with `types-mysqlclient` itself, but with its runtime dependency.fixBefore `pip install mysqlclient`, ensure you install required system packages like `python3-dev`, `default-libmysqlclient-dev` (Ubuntu/Debian), or `python3-devel`, `mysql-devel` (Red Hat/CentOS), along with `build-essential` and `pkg-config`.
affects: All versions of mysqlclient and types-mysqlclient
gotchaWhen using `cursor.execute()` with SQL statements that contain literal percent signs (`%`), they must be escaped as `%%` if they are not intended as parameter placeholders. Failure to do so can lead to `TypeError: not all arguments converted during string formatting` or incorrect query execution.fixChange literal `%` to `%%` in your SQL query strings where you don't intend it to be a parameter placeholder. Example: `cursor.execute("SELECT '50%% complete' AS progress;")` affects: All versions of mysqlclient
deprecatedThe direct use of the low-level `_mysql` module, which is part of the `mysqlclient` package, is discouraged. It is less portable and works at a lower level of abstraction than `MySQLdb`.fixAlways import and use `MySQLdb` instead of `_mysql` for database interactions to ensure adherence to the Python DB API Specification (PEP 249) and better portability.
affects: All versions of mysqlclient
Upgrade
Version history
2.2.0.20260508latest on PyPI · released May 8, 2026
Audit
Dependencies
mysqlclientrequiredRuntime dependency for which these stubs provide types.
python3-devrequiredRequired system headers for building mysqlclient.
default-libmysqlclient-devrequiredRequired MySQL client development libraries for building mysqlclient (Debian/Ubuntu).
mysql-develrequiredRequired MySQL client development libraries for building mysqlclient (Red Hat/CentOS).
build-essentialrequiredGeneral build tools for compiling C extensions (Debian/Ubuntu).
pkg-configrequiredTool to locate and configure build dependencies.