Using Postgres with Qt & Python on Windows, fixing QPSQL driver not loaded

If you're trying to use PostgreSQL with PyQt5, PyQt6, PySide2, or PySide6 you may have encountered the frustrating "QPSQL driver not loaded" error. Qt correctly lists the QPSQL driver as available, but when trying to load it the operation fails. This happens because the Qt PostgreSQL driver depends on Postgres' own native library (libpq.dll), which must be accessible on your system PATH.

In this guide, you'll learn how to diagnose and fix the QPSQL driver not loaded error on Windows, so you can successfully connect to PostgreSQL databases from your Python Qt applications.

Testing the PostgreSQL driver

The following script will let you test if the PostgreSQL QPSQL driver is loading correctly.

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

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PyQt6.QtSql import QSqlDatabase
from PyQt6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide2.QtSql import QSqlDatabase
from PySide2.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide6.QtSql import QSqlDatabase
from PySide6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

Understanding the "QPSQL driver not loaded" error

Executing the above script in a new command prompt will give the following output if the PostgreSQL native library is not accessible.

>python test.py
QSqlDatabase: QPSQL driver not loaded
QSqlDatabase: available drivers: QSQLITE QODBC QODBC3 QPSQL QPSQL7
Available drivers ['QSQLITE', 'QODBC', 'QODBC3', 'QPSQL', 'QPSQL7']
Unable to connect.
Last error Driver not loaded Driver not loaded

The list of "available drivers" shows the Qt SQL drivers which are available in your PyQt5 (or PyQt6, PySide2, or PySide6) installation. For example, in my installation the driver files are under site-packages\PyQt5\Qt5\plugins\sqldrivers

C:\Users\Martin\AppData\Local\Programs\Python\Python37\Lib\site-packages\PyQt5\Qt5\plugins\sqldrivers> dir

 Volume in drive C has no label.
 Volume Serial Number is 0A6A-65ED

 Directory of C:\Users\Martin\AppData\Local\Programs\Python\Python37\Lib\site-packages\PyQt5\Qt5\plugins\sqldrivers

02/12/2021  14:35    <DIR>          .
02/12/2021  14:35    <DIR>          ..
02/12/2021  14:35         1,412,080 qsqlite.dll
02/12/2021  14:35            98,288 qsqlodbc.dll
02/12/2021  14:35            79,856 qsqlpsql.dll
               3 File(s)      1,590,224 bytes
               2 Dir(s)  174,429,970,432 bytes free

The Driver not loaded error occurs because the Qt PostgreSQL driver (qsqlpsql.dll) is a wrapper around the native PostgreSQL client library — it is not a complete implementation of the PostgreSQL protocol itself. Without the native libpq.dll library available on your PATH, the Qt driver cannot load.

Fix: Add the PostgreSQL bin folder to your PATH

To fix the QPSQL driver not loaded error, you need to ensure the required PostgreSQL library files are available in your system PATH. You can do this by adding your PostgreSQL installation's bin folder to the PATH. For example, on my computer PostgreSQL is installed under C:\Program Files\PostgreSQL\14\ (version 14). The bin folder contains libpq.dll (the PostgreSQL client library) which Qt needs.

SET PATH=%PATH%;C:\Program Files\PostgreSQL\14\bin

T> Adjust the path above to match your PostgreSQL installation version and location. Common paths include C:\Program Files\PostgreSQL\15\bin or C:\Program Files\PostgreSQL\16\bin for newer versions.

With that in place, running the script again will show that the QPSQL driver has loaded successfully. The connection still isn't working, since it needs the username and password set. But if you get this far you know the driver is working properly.

U:\home\martin\www\pythonguis\content\faq\qt-postgres-driver>python test.py
Available drivers ['QSQLITE', 'QODBC', 'QODBC3', 'QPSQL', 'QPSQL7']
Unable to connect.
Last error connection to server at "localhost" (::1), port 5432 failed: fe_sendauth: no password supplied
QPSQL: Unable to connect

Connecting to PostgreSQL with username and password

We can modify the test script to add your username and password to complete the database connection.

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

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PyQt6.QtSql import QSqlDatabase
from PyQt6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide2.QtSql import QSqlDatabase
from PySide2.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide6.QtSql import QSqlDatabase
from PySide6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

With the correct credentials, the connection will complete as expected.

>python test-userpass.py
Available drivers ['QSQLITE', 'QODBC', 'QODBC3', 'QPSQL', 'QPSQL7']
Connection to the database successful

To make the PATH change permanent so you don't need to set it every time, you can add the PostgreSQL bin folder to your system environment variables through Windows Settings > System > Advanced system settings > Environment Variables.