1.. _installation: 2 3Installation 4============ 5 6.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com> 7 8Psycopg is a PostgreSQL_ adapter for the Python_ programming language. It is a 9wrapper for the libpq_, the official PostgreSQL client library. 10 11.. _PostgreSQL: https://www.postgresql.org/ 12.. _Python: https://www.python.org/ 13 14 15.. index:: 16 single: Install; from PyPI 17 single: Install; wheel 18 single: Wheel 19 20.. _binary-packages: 21 22Quick Install 23------------- 24 25For most operating systems, the quickest way to install Psycopg is using the 26wheel_ package available on PyPI_: 27 28.. code-block:: console 29 30 $ pip install psycopg2-binary 31 32This will install a pre-compiled binary version of the module which does not 33require the build or runtime prerequisites described below. Make sure to use 34an up-to-date version of :program:`pip` (you can upgrade it using something 35like ``pip install -U pip``). 36 37You may then import the ``psycopg2`` package, as usual: 38 39.. code-block:: python 40 41 import psycopg2 42 43 # Connect to your postgres DB 44 conn = psycopg2.connect("dbname=test user=postgres") 45 46 # Open a cursor to perform database operations 47 cur = conn.cursor() 48 49 # Execute a query 50 cur.execute("SELECT * FROM my_data") 51 52 # Retrieve query results 53 records = cur.fetchall() 54 55.. _PyPI: https://pypi.org/project/psycopg2-binary/ 56.. _wheel: https://pythonwheels.com/ 57 58 59psycopg vs psycopg-binary 60^^^^^^^^^^^^^^^^^^^^^^^^^ 61 62The ``psycopg2-binary`` package is meant for beginners to start playing 63with Python and PostgreSQL without the need to meet the build 64requirements. 65 66If you are the maintainer of a published package depending on `!psycopg2` 67you shouldn't use ``psycopg2-binary`` as a module dependency. **For 68production use you are advised to use the source distribution.** 69 70The binary packages come with their own versions of a few C libraries, 71among which ``libpq`` and ``libssl``, which will be used regardless of other 72libraries available on the client: upgrading the system libraries will not 73upgrade the libraries used by `!psycopg2`. Please build `!psycopg2` from 74source if you want to maintain binary upgradeability. 75 76.. warning:: 77 78 The `!psycopg2` wheel package comes packaged, among the others, with its 79 own ``libssl`` binary. This may create conflicts with other extension 80 modules binding with ``libssl`` as well, for instance with the Python 81 `ssl` module: in some cases, under concurrency, the interaction between 82 the two libraries may result in a segfault. In case of doubts you are 83 advised to use a package built from source. 84 85 86.. index:: 87 single: Install; disable wheel 88 single: Wheel; disable 89 90.. _disable-wheel: 91 92Change in binary packages between Psycopg 2.7 and 2.8 93^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 94 95In version 2.7.x, :command:`pip install psycopg2` would have tried to install 96automatically the binary package of Psycopg. Because of concurrency problems 97binary packages have displayed, ``psycopg2-binary`` has become a separate 98package, and from 2.8 it has become the only way to install the binary 99package. 100 101If you are using Psycopg 2.7 and you want to disable the use of wheel binary 102packages, relying on the system libraries available on your client, you 103can use the :command:`pip` |--no-binary option|__, e.g.: 104 105.. code-block:: console 106 107 $ pip install --no-binary :all: psycopg2 108 109.. |--no-binary option| replace:: ``--no-binary`` option 110.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-no-binary 111 112which can be specified in your :file:`requirements.txt` files too, e.g. use: 113 114.. code-block:: none 115 116 psycopg2>=2.7,<2.8 --no-binary psycopg2 117 118to use the last bugfix release of the `!psycopg2` 2.7 package, specifying to 119always compile it from source. Of course in this case you will have to meet 120the :ref:`build prerequisites <build-prerequisites>`. 121 122 123.. index:: 124 single: Prerequisites 125 126Prerequisites 127------------- 128 129The current `!psycopg2` implementation supports: 130 131.. 132 NOTE: keep consistent with setup.py and the /features/ page. 133 134- Python versions from 3.6 to 3.10 135- PostgreSQL server versions from 7.4 to 14 136- PostgreSQL client library version from 9.1 137 138 139 140.. _build-prerequisites: 141 142Build prerequisites 143^^^^^^^^^^^^^^^^^^^ 144 145The build prerequisites are to be met in order to install Psycopg from source 146code, from a source distribution package, GitHub_ or from PyPI. 147 148.. _GitHub: https://github.com/psycopg/psycopg2 149 150Psycopg is a C wrapper around the libpq_ PostgreSQL client library. To install 151it from sources you will need: 152 153- A C compiler. 154 155- The Python header files. They are usually installed in a package such as 156 **python-dev** or **python3-dev**. A message such as *error: Python.h: No 157 such file or directory* is an indication that the Python headers are 158 missing. 159 160- The libpq header files. They are usually installed in a package such as 161 **libpq-dev**. If you get an *error: libpq-fe.h: No such file or directory* 162 you are missing them. 163 164- The :program:`pg_config` program: it is usually installed by the 165 **libpq-dev** package but sometimes it is not in a :envvar:`PATH` directory. 166 Having it in the :envvar:`PATH` greatly streamlines the installation, so try 167 running ``pg_config --version``: if it returns an error or an unexpected 168 version number then locate the directory containing the :program:`pg_config` 169 shipped with the right libpq version (usually 170 ``/usr/lib/postgresql/X.Y/bin/``) and add it to the :envvar:`PATH`: 171 172 .. code-block:: console 173 174 $ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH 175 176 You only need :program:`pg_config` to compile `!psycopg2`, not for its 177 regular usage. 178 179Once everything is in place it's just a matter of running the standard: 180 181.. code-block:: console 182 183 $ pip install psycopg2 184 185or, from the directory containing the source code: 186 187.. code-block:: console 188 189 $ python setup.py build 190 $ python setup.py install 191 192 193Runtime requirements 194^^^^^^^^^^^^^^^^^^^^ 195 196Unless you compile `!psycopg2` as a static library, or you install it from a 197self-contained wheel package, it will need the libpq_ library at runtime 198(usually distributed in a ``libpq.so`` or ``libpq.dll`` file). `!psycopg2` 199relies on the host OS to find the library if the library is installed in a 200standard location there is usually no problem; if the library is in a 201non-standard location you will have to tell Psycopg how to find it, 202which is OS-dependent (for instance setting a suitable 203:envvar:`LD_LIBRARY_PATH` on Linux). 204 205.. note:: 206 207 The libpq header files used to compile `!psycopg2` should match the 208 version of the library linked at runtime. If you get errors about missing 209 or mismatching libraries when importing `!psycopg2` check (e.g. using 210 :program:`ldd`) if the module ``psycopg2/_psycopg.so`` is linked to the 211 right ``libpq.so``. 212 213.. note:: 214 215 Whatever version of libpq `!psycopg2` is compiled with, it will be 216 possible to connect to PostgreSQL servers of any supported version: just 217 install the most recent libpq version or the most practical, without 218 trying to match it to the version of the PostgreSQL server you will have 219 to connect to. 220 221 222.. index:: 223 single: setup.py 224 single: setup.cfg 225 226Non-standard builds 227------------------- 228 229If you have less standard requirements such as: 230 231- creating a :ref:`debug build <debug-build>`, 232- using :program:`pg_config` not in the :envvar:`PATH`, 233 234then take a look at the ``setup.cfg`` file. 235 236Some of the options available in ``setup.cfg`` are also available as command 237line arguments of the ``build_ext`` sub-command. For instance you can specify 238an alternate :program:`pg_config` location using: 239 240.. code-block:: console 241 242 $ python setup.py build_ext --pg-config /path/to/pg_config build 243 244Use ``python setup.py build_ext --help`` to get a list of the options 245supported. 246 247 248.. index:: 249 single: debug 250 single: PSYCOPG_DEBUG 251 252.. _debug-build: 253 254Creating a debug build 255^^^^^^^^^^^^^^^^^^^^^^ 256 257In case of problems, Psycopg can be configured to emit detailed debug 258messages, which can be very useful for diagnostics and to report a bug. In 259order to create a debug package: 260 261- `Download`__ and unpack the Psycopg *source package* (the ``.tar.gz`` 262 package). 263 264- Edit the ``setup.cfg`` file adding the ``PSYCOPG_DEBUG`` flag to the 265 ``define`` option. 266 267- :ref:`Compile and install <build-prerequisites>` the package. 268 269- Set the :envvar:`PSYCOPG_DEBUG` environment variable: 270 271.. code-block:: console 272 273 $ export PSYCOPG_DEBUG=1 274 275- Run your program (making sure that the `!psycopg2` package imported is the 276 one you just compiled and not e.g. the system one): you will have a copious 277 stream of informations printed on stderr. 278 279.. __: https://pypi.org/project/psycopg2/#files 280 281 282Non-standard Python Implementation 283^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 284 285The `psycopg2` package is the current mature implementation of the adapter: it 286is a C extension and as such it is only compatible with CPython_. If you want 287to use Psycopg on a different Python implementation (PyPy, Jython, IronPython) 288there is a couple of alternative: 289 290- a `Ctypes port`__, but it is not as mature as the C implementation yet 291 and it is not as feature-complete; 292 293- a `CFFI port`__ which is currently more used and reported more efficient on 294 PyPy, but please be careful of its version numbers because they are not 295 aligned to the official psycopg2 ones and some features may differ. 296 297.. _PostgreSQL: https://www.postgresql.org/ 298.. _Python: https://www.python.org/ 299.. _libpq: https://www.postgresql.org/docs/current/static/libpq.html 300.. _CPython: https://en.wikipedia.org/wiki/CPython 301.. _Ctypes: https://docs.python.org/library/ctypes.html 302.. __: https://github.com/mvantellingen/psycopg2-ctypes 303.. __: https://github.com/chtd/psycopg2cffi 304 305 306.. index:: 307 single: tests 308 309.. _test-suite: 310 311Running the test suite 312---------------------- 313 314Once `!psycopg2` is installed you can run the test suite to verify it is 315working correctly. From the source directory, you can run: 316 317.. code-block:: console 318 319 $ python -c "import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose 320 321The tests run against a database called ``psycopg2_test`` on UNIX socket and 322the standard port. You can configure a different database to run the test by 323setting the environment variables: 324 325- :envvar:`PSYCOPG2_TESTDB` 326- :envvar:`PSYCOPG2_TESTDB_HOST` 327- :envvar:`PSYCOPG2_TESTDB_PORT` 328- :envvar:`PSYCOPG2_TESTDB_USER` 329 330The database should already exist before running the tests. 331 332 333.. _other-problems: 334 335If you still have problems 336-------------------------- 337 338Try the following. *In order:* 339 340- Read again the :ref:`build-prerequisites`. 341 342- Read the :ref:`FAQ <faq-compile>`. 343 344- Google for `!psycopg2` *your error message*. Especially useful the week 345 after the release of a new OS X version. 346 347- Write to the `Mailing List`_. 348 349- If you think that you have discovered a bug, test failure or missing feature 350 please raise a ticket in the `bug tracker`_. 351 352- Complain on your blog or on Twitter that `!psycopg2` is the worst package 353 ever and about the quality time you have wasted figuring out the correct 354 :envvar:`ARCHFLAGS`. Especially useful from the Starbucks near you. 355 356.. _mailing list: https://www.postgresql.org/list/psycopg/ 357.. _bug tracker: https://github.com/psycopg/psycopg2/issues 358