psycopg2-binary: PostgreSQL Database Adapter for Python

2.9.11 verified Tue May 12 auth: no python install: verified quickstart: stale

psycopg2-binary is a PostgreSQL adapter for Python, providing a means to interact with PostgreSQL databases. The current version is 2.9.11, and it follows a regular release cadence with periodic updates and bug fixes.

pip install psycopg2-binary

Common errors

error Error: pg_config executable not found. ↓

cause This error occurs when `pip` tries to build `psycopg2` (or `psycopg2-binary` when a pre-compiled wheel isn't available for your specific Python/OS combination) from source, but the PostgreSQL development headers and `pg_config` utility are not installed or not found in the system's PATH.

fix

Ensure you are installing psycopg2-binary (which provides pre-compiled wheels) and that your pip is up-to-date. If the error persists, especially on Linux/macOS, it means a wheel isn't available, and you need to install PostgreSQL development packages before trying pip install psycopg2 or pip install psycopg2-binary. For Debian/Ubuntu: sudo apt-get install libpq-dev python3-dev. For Fedora/RHEL: sudo dnf install postgresql-devel python3-devel.

error ModuleNotFoundError: No module named 'psycopg2' ↓

cause This error indicates that the `psycopg2` or `psycopg2-binary` package is not installed in the Python environment you are currently using, or there's an issue with your Python environment's paths.

fix

Install the psycopg2-binary package using pip: pip install psycopg2-binary. Ensure you are running this command in the correct Python environment (e.g., your virtual environment) where your application will run.

error psycopg2.OperationalError: could not connect to server: No such file or directory Is the server running locally and accepting connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"? ↓

cause This `OperationalError` typically means that the Python application cannot establish a connection with the PostgreSQL database server. Common reasons include the PostgreSQL server not running, incorrect host or port in the connection string, or firewall issues blocking the connection.

fix

Verify that your PostgreSQL server is running and accessible. Check the connection parameters in your Python code (host, port, database name, user, password) against your PostgreSQL configuration. If connecting via a Unix socket, ensure the socket file exists and permissions are correct, or specify a TCP/IP connection with host='localhost' or the server's IP address.

error psycopg2.OperationalError: server closed the connection unexpectedly ↓

cause This error occurs when the PostgreSQL server unexpectedly terminates the connection while `psycopg2` is trying to communicate with it. This can be due to database server crashes, network instability, extended periods of inactivity (leading to timeouts), or improper connection handling in the application.

fix

Implement robust connection management, including connection pooling (e.g., using psycopg2.pool or a framework's ORM) to manage connection lifecycles and reconnections. Also, handle database exceptions in your code (e.g., using try-except blocks) to catch OperationalError and gracefully attempt to reconnect or retry the operation. Check PostgreSQL server logs for any issues, and review network stability.

Warnings

breaking Using 'psycopg2-binary' in production environments is discouraged due to potential conflicts with system libraries and lack of binary upgradeability. ↓

fix Use the source distribution 'psycopg2' for production environments.

deprecated The 'psycopg2.tz' module is deprecated and will be removed in psycopg2 version 2.10. ↓

fix Use 'datetime.timezone' instead.

breaking psycopg2.OperationalError: connection to server failed: No such file or directory, means the PostgreSQL server is either not running or not accessible from the application's environment. ↓

fix Ensure the PostgreSQL server is running and configured to accept connections at the specified host/socket, or verify the connection parameters (e.g., dbname, user, host, port, password) are correct for your environment.

breaking psycopg2.OperationalError: connection to server failed, indicating the PostgreSQL server is not running, not accessible, or connection parameters are incorrect. ↓

fix Ensure the PostgreSQL server is running and accessible from the application's environment. Verify all connection parameters (host, port, user, password, dbname) are correct. Check firewall rules or network configurations if connecting to a remote server.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 26.3M

3.10 slim (glibc) - - 0.03s 29M

3.11 alpine (musl) - - 0.07s 28.2M

3.11 slim (glibc) - - 0.05s 31M

3.12 alpine (musl) - - 0.05s 20.1M

3.12 slim (glibc) - - 0.05s 23M

3.13 alpine (musl) - - 0.05s 19.7M

3.13 slim (glibc) - - 0.05s 23M

3.9 alpine (musl) - - 0.04s 25.8M

3.9 slim (glibc) - - 0.04s 29M

Imports

connect
```
from psycopg2 import connect
```
Ensure 'psycopg2' is installed; 'psycopg2-binary' is a distribution that includes the 'psycopg2' package.

Quickstart stale last tested: 2026-04-23

A basic example demonstrating how to connect to a PostgreSQL database and execute a query using psycopg2.

import psycopg2

# Connect to your postgres DB
conn = psycopg2.connect(dbname='test', user='postgres', password='secret')

# Open a cursor to perform database operations
cur = conn.cursor()

# Execute a query
cur.execute('SELECT * FROM my_data')

# Retrieve query results
records = cur.fetchall()

# Don't forget to close the cursor and connection
cur.close()
conn.close()