Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DB
✓ from pg import DB
✗ from pg import db
DB is the class name for the classic PyGreSQL interface, not 'db' (lowercase).
pgdb
✓ import pgdb
For the DB-API 2.0 compliant interface.
This quickstart demonstrates how to connect to a PostgreSQL database using PyGreSQL's classic interface, create a table (if it doesn't exist), insert data, and fetch results. It uses environment variables for connection parameters for security and flexibility.
import os
from pg import DB
dbname = os.environ.get('PG_DBNAME', 'testdb')
host = os.environ.get('PG_HOST', 'localhost')
port = int(os.environ.get('PG_PORT', 5432))
user = os.environ.get('PG_USER', 'postgres')
passwd = os.environ.get('PG_PASSWORD', 'mysecretpassword')
conn = None
try:
# Connect using the classic interface
conn = DB(dbname=dbname, host=host, port=port, user=user, passwd=passwd)
print(f"Successfully connected to PostgreSQL database '{dbname}'")
# Execute a simple query
conn.query("CREATE TABLE IF NOT EXISTS test_table (id SERIAL PRIMARY KEY, name VARCHAR(255))")
print("Table 'test_table' ensured to exist.")
# Insert data
insert_result = conn.insert('test_table', name='PyGreSQL Example')
print(f"Inserted data: {insert_result}")
# Fetch data
results = conn.query("SELECT id, name FROM test_table").getresult()
print("Fetched data:")
for row_id, row_name in results:
print(f" ID: {row_id}, Name: {row_name}")
except Exception as e:
print(f"An error occurred: {e}")
finally:
if conn:
conn.close()
print("Database connection closed.")
Debug
Known issues
breakingPyGreSQL 6.x and newer officially dropped support for Python 2 and older Python 3 versions (pre-3.8). It now exclusively supports Python 3.8 to 3.14. If you are on an older Python version, you must use PyGreSQL 5.x or upgrade Python.fixEnsure your Python environment is 3.8 or newer. If not, upgrade Python or pin PyGreSQL to a 5.x version (e.g., `PyGreSQL==5.2.5`).
affects: >=6.0
gotchaPyGreSQL requires the PostgreSQL client library (`libpq`) to be installed on the system, in addition to the Python package. `pip install PyGreSQL` installs the Python wrapper, but not the underlying C library.fixInstall `libpq` via your system's package manager (e.g., `sudo apt-get install libpq5` on Debian/Ubuntu, `brew install libpq` on macOS, or install PostgreSQL client tools on Windows). Ensure its DLL/shared library is in your system's `PATH` on Windows.
affects: All versions
gotchaWhen installing PyGreSQL from source, you need a C compiler and PostgreSQL development header files (e.g., `libpq-dev` or `postgresql-devel` packages) installed on your system. Without these, the `pip install` command will fail during compilation.fixInstall development packages for PostgreSQL and Python headers (e.g., `sudo apt-get install build-essential libpq-dev python3-dev` on Linux). Ensure the `pg_config` tool is available in your system's PATH.
affects: All versions when installing from source
deprecatedAs of PyGreSQL 6.0b1, the `pg.pgnotify()` function and the `ntuples()` method of the `pg.Query` object have been removed.fixAvoid using `pg.pgnotify()` and `pg.Query.ntuples()`. For row counts, you can use `len(query_result)` or similar methods depending on how you process the results. Consult the official documentation for alternatives.
affects: >=6.0b1
Errors
Common errors & fixes
ImportError: DLL load failed: The specified module could not be found.
The `libpq` C-interface library (e.g., `libpq.dll` on Windows, `_pg.so` on Linux) is missing or not in the system's dynamic library search path (e.g., `PATH` on Windows, `LD_LIBRARY_PATH` on Linux).
fixInstall the PostgreSQL client library for your operating system (e.g., `libpq-dev` on Debian/Ubuntu, PostgreSQL installer for Windows) and ensure its location is added to your system's PATH environment variable.
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-build-.../pygresql/
This typically occurs during `pip install PyGreSQL` when the system lacks the necessary PostgreSQL development headers (`libpq-dev`) or `pg_config` tool required to compile the underlying C extension.
fixInstall the PostgreSQL development packages and Python development headers for your system (e.g., `sudo apt-get install build-essential libpq-dev python3-dev` on Debian/Ubuntu, `sudo yum install gcc python3-devel postgresql-devel` on RHEL/CentOS, `brew install libpq` on macOS).
ERROR: permission denied for table "my_table"
The PostgreSQL user attempting to perform an operation (e.g., SELECT, INSERT, UPDATE, DELETE) on the specified table does not have the necessary privileges.
fixGrant appropriate database privileges to the connecting user in PostgreSQL using SQL commands, for example: `GRANT ALL PRIVILEGES ON TABLE my_table TO my_user;` or `GRANT SELECT, INSERT ON my_table TO my_user;`. Also, ensure the user has privileges on the schema if applicable.
Upgrade
Version history
6.2.3latest on PyPI · released Jan 25, 2026
Audit
Dependencies
libpqrequiredPyGreSQL is a C extension that wraps PostgreSQL's libpq C API library. This must be installed on the system (e.g., libpq.dll on Windows, libpq.so on Linux/macOS).
PostgreSQL development headersoptionalRequired for compiling PyGreSQL from source, typically provided by packages like 'libpq-dev' (Debian/Ubuntu) or 'postgresql-devel' (CentOS/RHEL).