PyQt5 MYSQL driver not loaded on Windows — How to fix the "QMYSQL driver not loaded" error when connecting to MySQL from PyQt5

2020-08-19T09:00:00+00:00

The QMYSQL driver not loaded error is one of the most common stumbling blocks when trying to use PyQt5 with a MySQL database on Windows. You'll typically see something like this when running your script:

python

QSqlDatabase: QMYSQL driver not loaded
QSqlDatabase: available drivers: QSQLITE QMYSQL QMYSQL3 QODBC QODBC3 QPSQL QPSQL7

This is confusing because the output lists QMYSQL as an available driver -- so why can't it load? The answer comes down to a missing dependency: the MySQL client library DLL. The Qt MySQL plugin (qsqlmysql.dll) is a thin wrapper that relies on the MySQL C Connector library to actually talk to the database. If that library isn't where Qt can find it, the plugin fails to load.

Let's walk through how to fix this.

Understanding the Problem

Qt's SQL system works with plugins. When you call QSqlDatabase.addDatabase('QMYSQL'), Qt looks for a plugin file (on Windows, qsqlmysql.dll) in its sqldrivers plugin directory. That plugin file itself depends on the MySQL C client library -- a separate DLL provided by MySQL, not by Qt or PyQt5.

If Qt finds the plugin file but can't load it (because the MySQL client library is missing or can't be found), you get the "driver not loaded" error. The driver is listed as available because the plugin file exists, but it can't actually be used because its dependency is missing.

Finding Your PyQt5 Plugin Directory

First, let's confirm where your PyQt5 installation keeps its SQL driver plugins. Open a Python prompt and run:

python

import os
from PyQt5.QtCore import QLibraryInfo

plugin_path = QLibraryInfo.location(QLibraryInfo.PluginsPath)
sqldrivers_path = os.path.join(plugin_path, "sqldrivers")
print("Plugin path:", plugin_path)
print("SQL drivers path:", sqldrivers_path)
print("Files:", os.listdir(sqldrivers_path))

You should see qsqlmysql.dll (or qsqlmysqld.dll for debug builds) listed among the files. If it's there, your Qt installation already has the MySQL plugin -- it just can't load it because of the missing dependency.

Getting the MySQL Client Library

You need the MySQL C Connector client library DLL. The specific file you need is called libmysql.dll. There are two ways to get it.

Option 1: From an Existing MySQL Installation

If you already have MySQL 8 installed on your machine, libmysql.dll is probably already on your system. Look in your MySQL installation directory, typically something like:

python

C:\Program Files\MySQL\MySQL Server 8.0\lib\

You should find libmysql.dll in that lib folder.

Option 2: Download the MySQL C Connector

If you don't have a full MySQL server installed locally (for example, you're connecting to a remote database), you can download just the connector:

Go to the MySQL Community Downloads page (or search for "MySQL Connector/C").
Download the Windows (x86, 64-bit) ZIP archive (choose the architecture that matches your Python installation -- if you're using 64-bit Python, get the 64-bit connector).
Extract the ZIP and find libmysql.dll in the lib directory.

Architecture matters here. If your Python installation is 64-bit, you need the 64-bit libmysql.dll. Mixing 32-bit and 64-bit will cause the same "driver not loaded" error. You can check your Python architecture by running:

python

import struct
print(struct.calcsize("P") * 8, "bit")

Placing the DLL Where Qt Can Find It

Once you have libmysql.dll, you need to put it somewhere that Windows can find it when Qt tries to load the MySQL plugin. There are a few options.

Option A: Copy It Next to Your Python Executable (Recommended)

The simplest approach is to copy libmysql.dll into the same directory as your python.exe. If you're using a virtual environment, that's the Scripts folder of your venv. If you're using a system Python installation, it's wherever python.exe lives.

Find your Python executable location with:

python

import sys
print(sys.executable)

Copy libmysql.dll into that directory.

Option B: Copy It into the SQL Drivers Plugin Directory

You can also place libmysql.dll directly into the sqldrivers directory alongside qsqlmysql.dll. Use the path you found earlier with QLibraryInfo.

Option C: Add the MySQL lib Directory to Your PATH

Instead of copying files around, you can add the directory containing libmysql.dll to your Windows PATH environment variable. For example, if libmysql.dll is in C:\Program Files\MySQL\MySQL Server 8.0\lib\, add that path to your system or user PATH.

After modifying PATH, restart your terminal or IDE for the change to take effect.

Additional Dependencies: OpenSSL

MySQL 8 uses encrypted connections by default, and libmysql.dll from MySQL 8 may also depend on OpenSSL libraries (libssl-1_1-x64.dll and libcrypto-1_1-x64.dll, or similar names depending on your MySQL version). If you place libmysql.dll and the connection still fails, these OpenSSL DLLs might also be missing.

You can find them in the same MySQL installation directory (or connector download) as libmysql.dll. Copy them to the same location where you placed libmysql.dll.

Testing the Fix

Here's a short script you can use to verify that the MySQL driver loads correctly and can connect to your database:

python

import sys
from PyQt5.QtWidgets import QApplication
from PyQt5.QtSql import QSqlDatabase

app = QApplication(sys.argv)

# Check available drivers
print("Available drivers:", QSqlDatabase.drivers())

# Try to load the MySQL driver
db = QSqlDatabase.addDatabase("QMYSQL")
db.setHostName("localhost")
db.setDatabaseName("your_database_name")
db.setUserName("your_username")
db.setPassword("your_password")

if db.open():
    print("Connected successfully!")
    db.close()
else:
    print("Connection failed:", db.lastError().text())

Replace the database name, username, and password with your own. If everything is set up correctly, you should see "Connected successfully!" printed to the console.

A Complete Working Example

Once the driver is loading properly, here's a complete example that connects to a MySQL database and displays a table in a QTableView, similar to the original goal:

python

import sys

from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import (
    QApplication,
    QMainWindow,
    QTableView,
    QMessageBox,
)
from PyQt5.QtSql import QSqlDatabase, QSqlTableModel


class MainWindow(QMainWindow):
    def __init__(self, db):
        super().__init__()
        self.setWindowTitle("MySQL Table Viewer")
        self.resize(600, 400)

        # Set up the model
        self.model = QSqlTableModel(self, db)
        self.model.setTable("your_table_name")  # Change this to your table
        self.model.select()

        # Set up the view
        table_view = QTableView()
        table_view.setModel(self.model)
        table_view.resizeColumnsToContents()

        self.setCentralWidget(table_view)


def main():
    app = QApplication(sys.argv)

    # Set up the database connection
    db = QSqlDatabase.addDatabase("QMYSQL")
    db.setHostName("localhost")
    db.setDatabaseName("your_database_name")
    db.setUserName("your_username")
    db.setPassword("your_password")

    if not db.open():
        QMessageBox.critical(
            None,
            "Database Error",
            f"Could not open database:\n{db.lastError().text()}",
        )
        return 1

    window = MainWindow(db)
    window.show()

    result = app.exec_()
    db.close()
    return result


if __name__ == "__main__":
    sys.exit(main())

Replace your_table_name, your_database_name, your_username, and your_password with your actual values. If the MySQL driver is set up correctly, this will display the contents of your table in a window.

Troubleshooting Checklist

If you're still getting the error after following the steps above, work through this checklist:

Architecture mismatch: Make sure your libmysql.dll matches the bitness of your Python installation (both 64-bit or both 32-bit).
Missing OpenSSL DLLs: MySQL 8's libmysql.dll often requires OpenSSL libraries. Copy them from the same MySQL directory.
Wrong MySQL version: Try to use a libmysql.dll from a MySQL version close to the one your server is running.
Virtual environment: If you're using a venv, make sure you're placing libmysql.dll relative to the venv's Python executable, not your system Python.
Restart your terminal: If you changed PATH, your current terminal session won't see the update until you restart it.

Using ODBC as an Alternative

If you continue to have trouble with the QMYSQL driver, you can use the QODBC driver instead as a workaround. Install the MySQL ODBC Connector and connect using an ODBC connection string:

python

db = QSqlDatabase.addDatabase("QODBC")
db.setDatabaseName(
    "DRIVER={MySQL ODBC 8.0 Unicode Driver};"
    "SERVER=localhost;"
    "DATABASE=your_database_name;"
    "USER=your_username;"
    "PASSWORD=your_password;"
)

This sidesteps the libmysql.dll issue entirely, since the ODBC driver manages its own MySQL connectivity. The ODBC driver name (e.g., MySQL ODBC 8.0 Unicode Driver) must match what's installed on your system -- you can check the installed ODBC drivers in the Windows ODBC Data Source Administrator.

For an in-depth guide to building Python GUIs with PyQt5 see my book, Create GUI Applications with Python & Qt5.

Python GUIs - mysql

PyQt5 MYSQL driver not loaded on Windows — How to fix the "QMYSQL driver not loaded" error when connecting to MySQL from PyQt5

Understanding the Problem

Finding Your PyQt5 Plugin Directory

Getting the MySQL Client Library

Option 1: From an Existing MySQL Installation

Option 2: Download the MySQL C Connector

Placing the DLL Where Qt Can Find It

Option A: Copy It Next to Your Python Executable (Recommended)

Option B: Copy It into the SQL Drivers Plugin Directory

Option C: Add the MySQL lib Directory to Your PATH

Additional Dependencies: OpenSSL

Testing the Fix

A Complete Working Example

Troubleshooting Checklist

Using ODBC as an Alternative