MySQL Connector/Python is a self-contained Python driver for communicating with MySQL servers, using an API that is compliant with the Python Database API Specification v2.0 (PEP 249). It also includes an implementation of the X DevAPI for working with the MySQL Document Store. The library is actively maintained, with its latest version (9.6.0) released in January 2026.
Install & Compatibility
Where this runs
tested against v9.7.0 · 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
py 3.10
10/11 runs
10/11 runs
py 3.11
10/11 runs
10/11 runs
py 3.12
10/11 runs
10/11 runs
py 3.13
10/11 runs
10/11 runs
py 3.9
10/11 runs
10/11 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connect
✓ from mysql.connector import connect
✗ import mysql.connector
This quickstart demonstrates how to establish a connection to a MySQL database, create a table (DDL), insert data (DML), and query data using `mysql.connector`. It highlights the importance of `conn.commit()` for data manipulation statements. Database credentials are retrieved from environment variables for security.
import os
import mysql.connector
from mysql.connector import Error
host = os.environ.get('MYSQL_HOST', 'localhost')
user = os.environ.get('MYSQL_USER', 'root')
password = os.environ.get('MYSQL_PASSWORD', 'your_password')
database = os.environ.get('MYSQL_DATABASE', 'test_db')
conn = None
try:
conn = mysql.connector.connect(
host=host,
user=user,
password=password,
database=database
)
if conn.is_connected():
print(f"Connected to MySQL database: {database}")
cursor = conn.cursor()
# Create a table (DDL - auto-commits)
cursor.execute("CREATE TABLE IF NOT EXISTS users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255), email VARCHAR(255))")
print("Table 'users' ensured to exist.")
# Insert data (DML - requires commit)
sql_insert = "INSERT INTO users (name, email) VALUES (%s, %s)"
data_to_insert = ("Alice", "alice@example.com")
cursor.execute(sql_insert, data_to_insert)
conn.commit() # Important: Commit changes for DML operations
print(f"Inserted: {cursor.rowcount} row(s)")
# Select data
cursor.execute("SELECT id, name, email FROM users")
records = cursor.fetchall()
print("\nData from 'users' table:")
for row in records:
print(row)
else:
print("Failed to connect to MySQL database.")
except Error as e:
print(f"Error connecting to MySQL: {e}")
finally:
if conn and conn.is_connected():
conn.close()
print("MySQL connection closed.")
mysql-connector-python --version
Debug
Known issues
gotchaData Manipulation Language (DML) operations (e.g., INSERT, UPDATE, DELETE) are not automatically committed to the database. You must explicitly call `connection.commit()` after executing DML statements for changes to persist. Data Definition Language (DDL) operations (e.g., CREATE TABLE, ALTER TABLE) are auto-committed.fixAlways call `connection.commit()` after `cursor.execute()` for DML statements within a transaction block, or if `autocommit` is not enabled.
affects: All versions
gotchaBy default, MySQL Connector/Python attempts to use a C extension for improved performance. If the `libmysqlclient` library is missing or incompatible on your system (e.g., specific Python versions or platforms), this can lead to connection errors or failures. Setting `use_pure=True` in the `connect()` call forces the use of the pure Python implementation.fixAdd `use_pure=True` to your `mysql.connector.connect()` parameters, e.g., `mysql.connector.connect(..., use_pure=True)`.
affects: Versions 2.1.1 and higher, particularly affecting environments where the C extension is problematic.
breakingX DevAPI support, which was previously part of the `mysql-connector-python` package, was separated into its own distinct package (`mysqlx-connector-python`) starting from version 8.3.0.fixFor X DevAPI functionality, install `mysqlx-connector-python` via `pip install mysqlx-connector-python` and import from `mysqlx` instead of `mysql.connector`.
affects: 8.3.0 and later
gotchaMySQL Connector/Python does not support old MySQL Server authentication methods. This means it will not work with MySQL server versions prior to 4.1.fixEnsure your MySQL server version is 4.1 or higher. It is recommended to use MySQL Server version 8.0 or higher with the latest Connector/Python versions.
affects: All versions of mysql-connector-python
gotchaFrequent `mysql.connector.errors.OperationalError` often indicates underlying issues such as incorrect database credentials (host, user, password, database), network problems (firewall, unreachable host), or the MySQL server being down or inaccessible.fixVerify all connection parameters are correct, check network connectivity, ensure the MySQL server is running and accessible from the client, and review MySQL server logs for connection attempts/failures. Implement robust exception handling and connection pooling for production applications.
affects: All versions
Audit
Dependencies
dnspythonoptionalOptional, for DNS SRV record support.
gssapioptionalOptional, for GSSAPI authentication.