{"id":999,"library":"mysqlclient","title":"mysqlclient","description":"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.","status":"active","version":"2.2.8","language":"python","source_language":"en","source_url":"https://github.com/PyMySQL/mysqlclient","tags":["database","mysql","sql","db-api"],"install":[{"cmd":"pip install mysqlclient","lang":"bash","label":"Basic Installation"},{"cmd":"sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config\npip install mysqlclient","lang":"bash","label":"Debian/Ubuntu (with system dependencies)"},{"cmd":"sudo yum install python3-devel mysql-devel pkgconfig\npip install mysqlclient","lang":"bash","label":"Red Hat/CentOS (with system dependencies)"},{"cmd":"brew install mysql pkg-config\npip install mysqlclient","lang":"bash","label":"macOS (Homebrew, with system dependencies)"}],"dependencies":[{"reason":"mysqlclient is a C extension and requires Python development headers for compilation. Examples: python3-dev (Debian/Ubuntu), python3-devel (Red Hat/CentOS).","package":"Python 3 Development Headers","optional":false},{"reason":"mysqlclient links against the MySQL C API (libmysqlclient). Examples: default-libmysqlclient-dev (Debian/Ubuntu), mysql-devel (Red Hat/CentOS), mysql-connector-c (macOS).","package":"MySQL Client Development Headers and Libraries","optional":false},{"reason":"The 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).","package":"C/C++ Compiler","optional":false},{"reason":"On POSIX systems, mysqlclient uses pkg-config to find compiler/linker flags. It is required for successful compilation if pre-built wheels are not available.","package":"pkg-config","optional":false}],"imports":[{"note":"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.","wrong":"import _mysql","symbol":"MySQLdb","correct":"import MySQLdb"},{"symbol":"connect","correct":"from MySQLdb import connect"}],"quickstart":{"code":"import MySQLdb\nimport os\n\nDB_HOST = os.environ.get('MYSQL_HOST', '127.0.0.1')\nDB_USER = os.environ.get('MYSQL_USER', 'root')\nDB_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'your_password') # Replace with a secure method for production\nDB_NAME = os.environ.get('MYSQL_DATABASE', 'testdb')\n\ntry:\n    # Establish a connection\n    conn = MySQLdb.connect(\n        host=DB_HOST,\n        user=DB_USER,\n        password=DB_PASSWORD,\n        database=DB_NAME\n    )\n    cursor = conn.cursor()\n\n    # Execute a query\n    cursor.execute(\"SELECT VERSION();\")\n    version = cursor.fetchone()\n    print(f\"Database version: {version[0]}\")\n\n    # Example: Create a table (if it doesn't exist)\n    cursor.execute(\"CREATE TABLE IF NOT EXISTS my_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))\")\n    print(\"Table 'my_table' ensured.\")\n\n    # Example: Insert data\n    cursor.execute(\"INSERT INTO my_table (name) VALUES (%s)\", (\"Test Name\",))\n    conn.commit()\n    print(\"Data inserted.\")\n\n    # Example: Read data\n    cursor.execute(\"SELECT id, name FROM my_table\")\n    rows = cursor.fetchall()\n    for row in rows:\n        print(f\"ID: {row[0]}, Name: {row[1]}\")\n\nfinally:\n    # Close the cursor and connection\n    if 'cursor' in locals() and cursor:\n        cursor.close()\n    if 'conn' in locals() and conn:\n        conn.close()\n    print(\"Database connection closed.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Installation 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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"In 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.","severity":"breaking","affected_versions":">=2.2.0"},{"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,)])`.","message":"The `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.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Use `password` and `database` keyword arguments instead.","message":"The `passwd` and `db` keyword arguments in the `MySQLdb.connect()` function are deprecated. They will be removed in future versions.","severity":"deprecated","affected_versions":">=2.1.0"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":">=2.2.8"},{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=2.2.2 (warning will appear in future versions)"},{"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\"`.","message":"On 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.","severity":"gotcha","affected_versions":"All versions on macOS with problematic `mysql-connector-c` installations"}],"env_vars":null,"last_verified":"2026-05-12T22:28:35.871Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Use `import MySQLdb` in your Python code after installing `mysqlclient` with `pip install mysqlclient`.","cause":"The `mysqlclient` library, despite its package name, provides the `_mysql` C extension and is typically imported in Python code using `import MySQLdb`.","error":"ModuleNotFoundError: No module named 'MySQLdb'"},{"fix":"Install the necessary MySQL development packages for your operating system. For Debian/Ubuntu, use `sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config`. For Red Hat/CentOS, use `sudo yum install python3-devel mysql-devel pkgconfig`. On macOS with Homebrew, you may need `brew install mysql-connector-c` or ensure MySQL is linked correctly.","cause":"Building `mysqlclient` from source requires the MySQL client development headers and libraries (which include `mysql_config`) to be installed on your system. This error typically occurs on Linux/macOS when these system-level dependencies are missing.","error":"EnvironmentError: mysql_config not found"},{"fix":"1. Ensure the MySQL server is running. 2. Verify the host and port are correct in your connection string (e.g., `host='127.0.0.1'`, `port=3306`). 3. Check your system's firewall rules to ensure port 3306 is open. 4. In `my.cnf` (MySQL configuration), ensure `bind-address` is correctly set (e.g., `0.0.0.0` or the specific IP) and `skip-networking` is commented out.","cause":"This error indicates that the Python application could not establish a TCP/IP connection to the MySQL server. Common reasons include the MySQL server not running, an incorrect host or port, a firewall blocking the connection, or the MySQL server not being configured to accept network connections.","error":"OperationalError: (2003, \"Can't connect to MySQL server on 'localhost' (10061)\")"},{"fix":"If `mysqlclient` is installed, the correct way to establish a connection is `import MySQLdb; conn = MySQLdb.connect(host='...', user='...', password='...', database='...')`. If you intend to use `mysql.connector`, you must install it (`pip install mysql-connector-python`) and import it as `import mysql.connector`.","cause":"This error often occurs when `mysqlclient` is installed, but the Python code is attempting to use the connection syntax specific to `mysql-connector-python` (e.g., `mysql.connector.connect()`). `mysqlclient` does not expose a `connector` module in this way.","error":"AttributeError: module 'mysql.connector' has no attribute 'connect'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.2.8","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":2.7,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":2.8,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":2.7,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":2.3,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":3.3,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}