PyGreSQL

6.2.3 · active · verified Thu Apr 16

PyGreSQL is a Python module that provides an interface to PostgreSQL databases, wrapping the lower-level C API library `libpq`. It allows Python applications to leverage powerful PostgreSQL features directly from Python. The current stable version is 6.2.3, released on January 25, 2026, and it primarily supports Python 3.8 to 3.14 and PostgreSQL 12 to 18. The project is actively maintained.

Common errors

```
ImportError: DLL load failed: The specified module could not be found.
```
cause 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).

fix Install 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/
```
cause 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.

fix Install 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"
```
cause The PostgreSQL user attempting to perform an operation (e.g., SELECT, INSERT, UPDATE, DELETE) on the specified table does not have the necessary privileges.

fix Grant 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.

Warnings

breaking PyGreSQL 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.
Fix: Ensure 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`).
gotcha PyGreSQL 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.
Fix: Install `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.
gotcha When 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.
Fix: Install 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.
deprecated As of PyGreSQL 6.0b1, the `pg.pgnotify()` function and the `ntuples()` method of the `pg.Query` object have been removed.
Fix: Avoid 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.

Install

pip install PyGreSQL Basic installation
sudo apt-get install libpq-dev python3-dev # Debian/Ubuntu sudo yum install postgresql-devel python3-devel # CentOS/RHEL # On macOS, use Homebrew to install PostgreSQL client libraries: brew install libpq System dependencies for compilation (Linux/macOS)

Imports

DB
wrong:
```
from pg import db
```
correct:
```
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.

Quickstart

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.")

view raw JSON →