From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat, 4 Oct 2025 16:33:40 +0000 (+0200)
Subject: docs: document the package to install in the "from psycopg2" page
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c440f4d6da5b77a470253a828b1715c1e1d7840c;p=thirdparty%2Fpsycopg.git

docs: document the package to install in the "from psycopg2" page

See #1156.
---

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index b1fa2e0a4..bd13f9bd7 100644
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -19,6 +19,33 @@ differences to be aware of.
     writing a program that should work with both Psycopg 2 and 3.
 
 
+.. _install-difference:
+
+Which package to install?
+-------------------------
+
+.. important::
+
+    - If you were installing ``psycopg2-binary`` you should now install
+      ``psycopg[binary]`` instead.
+
+    - If you were installing ``psycopg2``, therefore your client has the
+      prerequisites to build the C extension yourself, you can install
+      ``psycopg[c]`` instead.
+
+Please see the :ref:`installation <installation>` section for all the details.
+
+Rationale: both the ``psycopg2`` and the ``psycopg2-binary`` distribution
+packages install the ``psycopg2`` Python package. This scenario is not well
+covered by Python packaging metadata, resulting in complex dependencies
+management and problems if both the packages are installed.
+
+In Psycopg 3 there is a clear "interface" package, ``psycopg``, and optional
+speed-up extensions that can be included in the dependencies of a service (but
+don't need to -- and shouldn't be -- included in the dependencies of a
+library). See :ref:`install-dependencies` for more details.
+
+
 .. _server-side-binding:
 
 Server-side binding
diff --git a/docs/basic/install.rst b/docs/basic/install.rst
index 00b4f5d25..16ad5893e 100644
--- a/docs/basic/install.rst
+++ b/docs/basic/install.rst
@@ -67,6 +67,10 @@ packages by running::
     pip install "psycopg[binary]"
 
 This will install a self-contained package with all the libraries needed.
+If you are coming from Psycopg 2, this is the equivalent of installing
+the ``psycopg2-binary`` package.
+
+
 **You will need pip 20.3 at least**: please run ``pip install --upgrade pip``
 to update it beforehand.
 
@@ -142,6 +146,11 @@ If your build prerequisites are in place you can run::
 
     pip install "psycopg[c]"
 
+This will install a self-contained package with all the libraries needed.
+If you are coming from Psycopg 2, this is the equivalent of installing
+the ``psycopg2`` package, both in terms of build requirements and system
+dependencies at runtime.
+
 .. warning::
 
    The local installation is not supported by PyPy.
@@ -192,6 +201,8 @@ install "psycopg[pool]"``, or install the `psycopg_pool` package separately,
 which would allow to specify the release to install more precisely.
 
 
+.. _install-dependencies:
+
 Handling dependencies
 ---------------------