{"id":367,"library":"psycopg2-binary","title":"psycopg2-binary: PostgreSQL Database Adapter for Python","description":"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.","status":"active","version":"2.9.11","language":"python","source_language":"en","source_url":"https://github.com/psycopg/psycopg2","tags":["PostgreSQL","Python","Database Adapter","psycopg2","psycopg2-binary"],"install":[{"cmd":"pip install psycopg2-binary","lang":"bash","label":"Install psycopg2-binary"}],"dependencies":[{"reason":"Required for PostgreSQL client library functionality","package":"libpq"},{"reason":"Required for SSL support","package":"libssl"}],"imports":[{"note":"Ensure 'psycopg2' is installed; 'psycopg2-binary' is a distribution that includes the 'psycopg2' package.","symbol":"connect","correct":"from psycopg2 import connect"}],"quickstart":{"code":"import psycopg2\n\n# Connect to your postgres DB\nconn = psycopg2.connect(dbname='test', user='postgres', password='secret')\n\n# Open a cursor to perform database operations\ncur = conn.cursor()\n\n# Execute a query\ncur.execute('SELECT * FROM my_data')\n\n# Retrieve query results\nrecords = cur.fetchall()\n\n# Don't forget to close the cursor and connection\ncur.close()\nconn.close()","lang":"python","description":"A basic example demonstrating how to connect to a PostgreSQL database and execute a query using psycopg2."},"warnings":[{"fix":"Use the source distribution 'psycopg2' for production environments.","message":"Using 'psycopg2-binary' in production environments is discouraged due to potential conflicts with system libraries and lack of binary upgradeability.","severity":"breaking","affected_versions":">=2.8"},{"fix":"Use 'datetime.timezone' instead.","message":"The 'psycopg2.tz' module is deprecated and will be removed in psycopg2 version 2.10.","severity":"deprecated","affected_versions":">=2.9"},{"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.","message":"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.","severity":"breaking","affected_versions":"*"},{"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.","message":"psycopg2.OperationalError: connection to server failed, indicating the PostgreSQL server is not running, not accessible, or connection parameters are incorrect.","severity":"breaking","affected_versions":">=2.7"}],"env_vars":null,"last_verified":"2026-05-12T13:19:42.648Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: pg_config executable not found."},{"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.","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.","error":"ModuleNotFoundError: No module named 'psycopg2'"},{"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.","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.","error":"psycopg2.OperationalError: could not connect to server: No such file or directory\n\tIs the server running locally and accepting connections on Unix domain socket \"/var/run/postgresql/.s.PGSQL.5432\"?"},{"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.","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.","error":"psycopg2.OperationalError: server closed the connection unexpectedly"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.4,"disk_size":"26.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":2.4,"disk_size":"29M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.1,"disk_size":"28.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.1,"disk_size":"31M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.1,"disk_size":"20.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.1,"disk_size":"23M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.1,"disk_size":"19.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.9,"disk_size":"23M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.2,"disk_size":"25.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.2,"disk_size":"29M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}