psycopg2-binary

library2.9.12pypypi✓ verified 27d ago

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.

database http-networking

pip install psycopg2-binary

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PSYCOPG2-BINARY

psycopg2-binary

databasepythonv2.9.12

Install

1.9s avg

Import

46ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.9.12 · 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

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.046s · 26.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.046s · 30MB

26MB installed

● package 26MB

Code

Verified usage

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

connect

✓ from psycopg2 import connect

Ensure 'psycopg2' is installed; 'psycopg2-binary' is a distribution that includes the 'psycopg2' package.

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()

Debug

Known issues

breakingUsing '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.

affects: >=2.8

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

fix

Use 'datetime.timezone' instead.

affects: >=2.9

breakingpsycopg2.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.

affects: *

breakingpsycopg2.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.

affects: >=2.7

Errors

Common errors & fixes

Error: pg_config executable not found.

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`.

ModuleNotFoundError: No module named 'psycopg2'

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.

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"?

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.

psycopg2.OperationalError: server closed the connection unexpectedly

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.

Upgrade

Version history

2.9.12latest on PyPI · released Apr 20, 2026

Audit

Dependencies

libpqrequiredRequired for PostgreSQL client library functionality

libsslrequiredRequired for SSL support

Agent activity

21 hits · last 30 days

node

Amazon

Resources

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

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

homepagehttps://psycopg.org/ ↗

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

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