psycopg-binary

library3.3.4pypypi✓ verified 10d ago

psycopg-binary is the pre-compiled binary distribution for Psycopg 3, a modern PostgreSQL database adapter for Python. It provides C optimizations for performance without requiring local build prerequisites. While `psycopg-binary` is the package name on PyPI, it acts as an optional component for the core `psycopg` library (Psycopg 3). It is actively maintained, currently at version 3.3.3, and follows a frequent release cadence, often aligning with new Python and PostgreSQL versions.

database

pip install "psycopg[binary,pool]"

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PSYCOPG-BINARY

psycopg-binary

databasepythonv3.3.4

Install

2.2s avg

Import

505ms

Disk

34MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

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

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.538s · 35.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.472s · 39MB

34MB installed

● package 34MB

Code

Verified usage

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

connect

✓ from psycopg import connect

✗ import psycopg_binary

`psycopg-binary` is an internal optimization module and should not be directly imported by users. The primary interface is `psycopg`. Importing `psycopg_binary` directly before `psycopg` can lead to `ImportError`.

This quickstart demonstrates how to establish a connection to a PostgreSQL database using Psycopg 3 (installed via `psycopg[binary]`), create a table, insert data, and query it. It uses environment variables for connection details for security and flexibility. The `with` statement ensures proper resource management.

import os import psycopg # Retrieve connection string from environment or use a default conn_str = os.environ.get( "PSYCOPG_CONN_STRING", "dbname=test user=postgres password=mysecretpassword host=localhost port=5432" ) try: # Establish a connection using a context manager for automatic closing with psycopg.connect(conn_str) as conn: # Open a cursor to perform database operations with conn.cursor() as cur: # Example: Create a table (if it doesn't exist) cur.execute("DROP TABLE IF EXISTS test_table") cur.execute("CREATE TABLE test_table (id SERIAL PRIMARY KEY, name VARCHAR(100))") # Example: Insert data cur.execute("INSERT INTO test_table (name) VALUES (%s)", ("Alice",)) cur.execute("INSERT INTO test_table (name) VALUES (%s)", ("Bob",)) # Commit the transaction (if not in autocommit mode, default is autocommit=False) conn.commit() # Example: Query data cur.execute("SELECT id, name FROM test_table ORDER BY id") print("--- Data from test_table ---") for record in cur: print(f"ID: {record[0]}, Name: {record[1]}") except psycopg.Error as e: print(f"Database error: {e}") # In a production application, you would handle this more robustly, # e.g., logging the error and potentially exiting or retrying.

Debug

Known issues

breakingThe `psycopg-binary` package provides C optimizations for Psycopg 3, but the primary library to import is `psycopg`. Do not `import psycopg_binary` directly. If migrating from `psycopg2-binary`, the installation command is `pip install "psycopg[binary]"` (or `"psycopg[binary,pool]"`), and the import path changes from `import psycopg2` to `import psycopg`.

fix

Install using `pip install "psycopg[binary,pool]"` and always `import psycopg` in your code.

affects: All versions of Psycopg 3 when migrating from Psycopg 2 or installing incorrectly

gotchaThe `psycopg-binary` package bundles its own versions of C libraries like `libpq` and `libssl`. This can lead to conflicts with other Python modules or system libraries (potentially causing segfaults, especially with Python's `ssl` module under concurrency). System library upgrades will not update the versions used by `psycopg-binary`. For production environments, building from source (`pip install psycopg[c]`) is often advised to link against system libraries.

fix

For production, consider installing `psycopg[c]` (which requires build tools and `libpq-dev`) or be aware of potential library conflicts. Test thoroughly in your target environment.

affects: All versions

breakingPsycopg 3 introduces several API changes compared to Psycopg 2. Key differences include server-side parameter binding (which can break queries like `SET TimeZone`), a redesigned connection pool, and different handling of date/time infinities. Refer to the official 'Differences from psycopg2' documentation for a complete list of changes.

fix

Review the official Psycopg 3 documentation for migration guides and adapt your code to the new API. Be especially careful with `SET` statements and date/time handling.

affects: All versions of Psycopg 3 when migrating from Psycopg 2

gotchaPsycopg 3.3.x officially supports Python versions from 3.10 to 3.14. Older Python versions (e.g., 3.8, 3.9, 3.7) are only supported by earlier Psycopg 3.x releases. Ensure your Python environment meets the requirements for the `psycopg-binary` version you are installing.

fix

Always check the release notes for the specific `psycopg` (and thus `psycopg-binary`) version for compatible Python versions, and ensure your environment is up-to-date.

affects: All versions (check specific Psycopg 3.x release notes for precise Python compatibility)

gotchaOlder versions of `psycopg[binary]` (prior to 3.1.11) had reports of high memory consumption, particularly for large `SELECT` queries, due to query caching. This issue was addressed in `psycopg` version 3.1.11.

fix

Ensure you are using `psycopg-binary` (via `psycopg[binary]`) version 3.1.11 or newer to benefit from memory usage improvements for large queries.

affects: < 3.1.11

breakingThe `psycopg` library failed to connect to the PostgreSQL database server because the server refused the connection. This typically indicates that the PostgreSQL server is not running, is not accessible from the client's network, or is not configured to accept TCP/IP connections on the specified host and port.

fix

Ensure the PostgreSQL database server is running and accessible from the application's environment. Verify network connectivity, firewall rules, and that the server is configured to listen on the correct host and port (e.g., check `listen_addresses` in `postgresql.conf` and client authentication rules in `pg_hba.conf`).

affects: All versions

breakingThe database connection failed because the PostgreSQL server was not running or was not accessible at the specified host and port. This is an infrastructure issue, not directly related to the Psycopg library's installation or usage.

fix

Ensure your PostgreSQL server is running and configured to accept connections on the specified host and port (e.g., '127.0.0.1', port 5432). Check server logs for startup errors and firewall rules.

affects: N/A

Errors

Common errors & fixes

ERROR: Could not find a version that satisfies the requirement psycopg-binary (from versions: none)

This error typically occurs when `pip` cannot find a pre-compiled wheel for `psycopg-binary` that matches your Python version, operating system, and architecture, often seen on newer or less common platforms like certain ARM-based Macs or specific Linux distributions where wheels might not be available yet.

fix

Try installing `psycopg` (the source distribution) which requires PostgreSQL development headers and a C compiler, or use a Python version/platform combination for which pre-built `psycopg-binary` wheels exist. For macOS M1/M2, ensure you have the latest `pip` and try installing `psycopg` if `psycopg-binary` fails. You might also need to install PostgreSQL via Homebrew (`brew install postgresql`) and its development libraries.

ModuleNotFoundError: No module named 'psycopg2'

This error happens when you have installed `psycopg-binary` (Psycopg 3) but are attempting to import the module using the old `psycopg2` name, or `psycopg2` itself is not installed. Psycopg 3 uses `import psycopg`.

fix

If you intended to use Psycopg 3, change your import statement from `import psycopg2` to `import psycopg`. If you genuinely need `psycopg2`, you must install it separately via `pip install psycopg2-binary`.

psycopg.OperationalError: could not connect to server: Connection refused

This is a runtime error indicating that the Python application could not establish a connection with the PostgreSQL database server. Common reasons include the PostgreSQL server not running, incorrect host or port in the connection string, firewall blocking the connection, or incorrect database credentials.

fix

Verify that the PostgreSQL server is running and accessible from the machine running your Python application. Double-check the `host`, `port`, `dbname`, `user`, and `password` in your `psycopg.connect()` call. Ensure no firewall rules are blocking the connection on either the client or server side.

AttributeError: 'Connection' object has no attribute 'mogrify'

`mogrify` is a method available on `psycopg.ClientCursor` objects, not directly on the `Connection` object, in Psycopg 3. You need to create a `ClientCursor` to use this method.

fix

When creating your cursor, specify `cursor_factory=psycopg.ClientCursor` to obtain a client-side cursor that supports the `mogrify` method. 
```python
import psycopg

conn = psycopg.connect(dbname='your_db', user='your_user', password='your_password', host='your_host', cursor_factory=psycopg.ClientCursor)
cur = conn.cursor()
query = "SELECT * FROM users WHERE id = %s"
mogrified_query = cur.mogrify(query, (1,))
print(mogrified_query)
```

Upgrade

Version history

3.3.4latest on PyPI · released May 1, 2026

Audit

Dependencies

psycopgrequiredThe core Psycopg 3 library, which psycopg-binary is an optimization component for. Automatically installed via 'psycopg[binary]'.

psycopg-pooloptionalProvides connection pooling functionalities for Psycopg 3. Automatically installed via 'psycopg[pool]'.

Agent activity

15 hits · last 30 days

node