psycopg

library3.3.3pypypi✓ verified 51d ago

psycopg v3 — the successor to psycopg2. Completely rewritten. Install is 'psycopg' (no number), import is 'import psycopg'. Supports both sync and native async (AsyncConnection). Current version: 3.3.3 (Mar 2026). NOT backward compatible with psycopg2 — several behavior changes. For new projects use psycopg over psycopg2. Django 4.2+ supports psycopg v3.

database

pip install psycopg

github ↗package ↗homepage ↗docs ↗changelog ↗

Install & Compatibility

Where this runs

tested against v3.3.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

11/15 runs

py 3.11

11/15 runs

py 3.12

11/15 runs

py 3.13

11/15 runs

py 3.9

11/15 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

psycopg

✓ import psycopg

✗ import psycopg

AsyncConnection

✓ from psycopg import AsyncConnection

Connection

✓ from psycopg import Connection

Minimal psycopg v3 sync connection with dict row factory.

# pip install psycopg import psycopg from psycopg.rows import dict_row # Sync usage with psycopg.connect( 'postgresql://user:pass@localhost/mydb', row_factory=dict_row ) as conn: with conn.cursor() as cur: cur.execute( 'SELECT id, name FROM users WHERE active = %s', (True,) ) for row in cur.fetchall(): print(row['name']) # dict access conn.commit()

Debug

Known issues

breaking'with connection' behavior changed from psycopg2. In psycopg2 it manages the transaction. In psycopg v3 it closes the connection. Major silent bug when migrating.

fix

Use 'with psycopg.connect(...) as conn:' for connection management. Use 'with conn.transaction():' for transaction blocks.

affects: psycopg >= 3.0

breakingcursor_factory moved from cursor() to connect(). psycopg2 pattern: conn.cursor(cursor_factory=DictCursor). psycopg v3: psycopg.connect(..., row_factory=dict_row).

fix

Pass row_factory=psycopg.rows.dict_row to connect() not cursor().

affects: psycopg >= 3.0

breakingPackage name changed. Install: 'psycopg' not 'psycopg3' or 'psycopg2'. Import: 'import psycopg' not 'import psycopg2'. LLMs confuse the package names.

fix

pip install psycopg; import psycopg

affects: all

gotchapsycopg2 and psycopg cannot be used interchangeably in the same codebase — APIs differ. Cannot drop-in replace 'import psycopg2' with 'import psycopg'.

fix

Treat migration as a deliberate refactor. Key differences at psycopg.org/psycopg3/docs/basic/from_pg2.html

affects: all

gotcharow_factory=dict_row is imported from psycopg.rows, not from psycopg directly. 'from psycopg import dict_row' fails.

fix

from psycopg.rows import dict_row — or use psycopg.rows.dict_row

affects: all

gotchaCOPY command API changed. psycopg2 had copy_expert(), copy_from(), copy_to(). psycopg v3 has a single copy() method with unified interface.

fix

Use conn.copy('COPY table FROM STDIN') context manager pattern.

affects: psycopg >= 3.0

breakingpsycopg.OperationalError: connection failed: Connection refused indicates the PostgreSQL server is not running, is not listening on the specified host/port, or is inaccessible (e.g., due to firewall rules). This is an infrastructure issue, not a psycopg library usage error.

fix

Ensure your PostgreSQL server is running and configured to accept connections on the specified host and port (e.g., 127.0.0.1:5432). Verify network connectivity and firewall settings if connecting to a remote server. Double-check connection parameters in your code.

affects: all

breakingConnection refused: psycopg.OperationalError when connecting to PostgreSQL. This error indicates that the database server is not running, is not accessible at the specified host/port, or is not configured to accept incoming connections from the client.

fix

Ensure the PostgreSQL server is running. Verify that the server is configured to listen on the correct host and port (default 5432). Check PostgreSQL's pg_hba.conf and postgresql.conf files to ensure connections are allowed from the client's IP address and for the specified user.

affects: all

Upgrade

Version history

3.3.4latest on PyPI

Audit

Dependencies

psycopg-binaryoptionalOptional C extension for better performance. Install via psycopg[binary].

Agent activity

17 hits · last 30 days

node

seranking-bot

ahrefsbot