psycopg2

library2.9.12pypypi✓ verified 28d ago

The most widely used PostgreSQL adapter for Python. Sync only. Two packages on PyPI: psycopg2 (source, requires libpq dev headers) and psycopg2-binary (pre-compiled, no system deps). Official docs explicitly warn against psycopg2-binary in production. Current version: 2.9.11 (Mar 2026). For async PostgreSQL use asyncpg or psycopg (v3). For new projects consider migrating to psycopg (v3) which has both sync and async.

database

pip install psycopg2-binary

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PSYCOPG2

psycopg2

databasepythonv2.9.12

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · 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

1/2 runs

py 3.11

1/2 runs

py 3.12

1/2 runs

py 3.13

1/2 runs

py 3.9

1/2 runs

Code

Verified usage

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

psycopg2

✓ import psycopg2

✗ import psycopg2

Minimal psycopg2 connection with RealDictCursor and parameterized query.

# Development: pip install psycopg2-binary # Production: pip install psycopg2 (requires libpq-dev) import psycopg2 import psycopg2.extras conn = psycopg2.connect( host='localhost', dbname='mydb', user='myuser', password='mypassword' ) with conn: with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur: # Parameterized query — always use %s cur.execute( 'SELECT * FROM users WHERE active = %s', (True,) # note: tuple, not single value ) users = cur.fetchall() for user in users: print(user['name']) conn.close()

Debug

Known issues

gotchapsycopg2-binary is NOT recommended for production. Official docs: 'The binary package is a practical choice for development and testing but in production it is advised to use the package built from source.' It bundles its own libpq which can conflict with system libraries.

fix

Use psycopg2-binary for development. In production use psycopg2 with system libpq: apt-get install libpq-dev && pip install psycopg2

affects: all

gotchaParameter placeholder is %s for ALL types — not ? (sqlite3) or :param (SQLAlchemy). Using ? raises ProgrammingError. Using f-strings creates SQL injection risk.

fix

Always: cur.execute('SELECT * FROM t WHERE id = %s', (value,)) — note the trailing comma to make a tuple.

affects: all

gotchaSingle-value parameterized queries need a tuple: cur.execute('SELECT %s', (value,)) — not cur.execute('SELECT %s', value). Passing a non-tuple raises TypeError or treats string as iterable of chars.

fix

Always wrap single values in a tuple: (value,) not value.

affects: all

gotchaDefault cursor returns rows as tuples. Accessing by column name raises TypeError. Use RealDictCursor or DictCursor from psycopg2.extras for dict access.

fix

cur = conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor)

affects: all

gotchapsycopg2 is sync only. Cannot be used in async contexts (FastAPI, asyncio) without blocking the event loop. Use asyncpg or psycopg (v3) for async.

fix

For async: pip install asyncpg or pip install psycopg[binary] (psycopg v3)

affects: all

gotchapsycopg2 ≠ psycopg (v3). They are different packages with different APIs. psycopg (without the 2) is the newer version — different install, different import patterns.

fix

psycopg2: 'import psycopg2'. psycopg v3: 'import psycopg'. Do not mix them.

affects: all

gotchaConnection is not thread-safe. Do not share a single psycopg2 connection across threads. Use a connection pool (psycopg2.pool or SQLAlchemy's pool).

fix

Use psycopg2.pool.ThreadedConnectionPool or let SQLAlchemy manage the pool.

affects: all

Upgrade

Version history

2.9.12latest on PyPI · released Apr 20, 2026

Audit

Dependencies

libpq-devrequiredSystem library required to build psycopg2 from source. Install via: apt-get install libpq-dev (Ubuntu) or brew install libpq (macOS).

Agent activity

19 hits · last 30 days

node

Resources

githubhttps://github.com/psycopg/psycopg2 ↗

packagehttps://pypi.org/project/psycopg2/ ↗

homepagehttps://psycopg.org/ ↗

docshttps://www.psycopg.org/docs/ ↗

changeloghttps://www.psycopg.org/docs/news.html ↗