$ pip install psycopg2-binary
This will install a pre-compiled binary version of the module which does not
require the build or runtime prerequisites described below. Make sure to use
an up-to-date version of pip (you can upgrade it using something
pip install -U pip).
You may then import the
psycopg2 package, as usual:
import psycopg2 # Connect to your postgres DB conn = psycopg2.connect("dbname=test user=postgres") # 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()
psycopg vs psycopg-binary¶
psycopg2-binary package is meant for beginners to start playing
with Python and PostgreSQL without the need to meet the build
If you are the maintainer of a published package depending on
you shouldn’t use
psycopg2-binary as a module dependency. For
production use you are advised to use the source distribution.
The binary packages come with their own versions of a few C libraries,
libssl, which will be used regardless of other
libraries available on the client: upgrading the system libraries will not
upgrade the libraries used by
psycopg2. Please build
source if you want to maintain binary upgradeability.
psycopg2 wheel package comes packaged, among the others, with its
libssl binary. This may create conflicts with other extension
modules binding with
libssl as well, for instance with the Python
ssl module: in some cases, under concurrency, the interaction between
the two libraries may result in a segfault. In case of doubts you are
advised to use a package built from source.
Change in binary packages between Psycopg 2.7 and 2.8¶
In version 2.7.x, pip install psycopg2 would have tried to install
automatically the binary package of Psycopg. Because of concurrency problems
binary packages have displayed,
psycopg2-binary has become a separate
package, and from 2.8 it has become the only way to install the binary
If you are using Psycopg 2.7 and you want to disable the use of wheel binary
packages, relying on the system libraries available on your client, you
can use the pip
--no-binary option, e.g.:
$ pip install --no-binary :all: psycopg2
which can be specified in your
requirements.txt files too, e.g. use:
psycopg2>=2.7,<2.8 --no-binary psycopg2
to use the last bugfix release of the
psycopg2 2.7 package, specifying to
always compile it from source. Of course in this case you will have to meet
the build prerequisites.
psycopg2 implementation supports:
Python versions from 3.7 to 3.12
PostgreSQL server versions from 7.4 to 16
PostgreSQL client library version from 9.1
Not all the psycopg2 versions support all the supported Python versions.
Please see the release notes to verify when the support for a new Python version was added and when the support for an old Python version was removed.
The build prerequisites are to be met in order to install Psycopg from source code, from a source distribution package, GitHub or from PyPI.
Psycopg is a C wrapper around the libpq PostgreSQL client library. To install it from sources you will need:
A C compiler.
The Python header files. They are usually installed in a package such as python-dev or python3-dev. A message such as error: Python.h: No such file or directory is an indication that the Python headers are missing.
The libpq header files. They are usually installed in a package such as libpq-dev. If you get an error: libpq-fe.h: No such file or directory you are missing them.
The pg_config program: it is usually installed by the libpq-dev package but sometimes it is not in a
PATHdirectory. Having it in the
PATHgreatly streamlines the installation, so try running
pg_config --version: if it returns an error or an unexpected version number then locate the directory containing the pg_config shipped with the right libpq version (usually
/usr/lib/postgresql/X.Y/bin/) and add it to the
$ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
You only need pg_config to compile
psycopg2, not for its regular usage.
Once everything is in place it’s just a matter of running the standard:
$ pip install psycopg2
or, from the directory containing the source code:
$ python setup.py build $ python setup.py install
Unless you compile
psycopg2 as a static library, or you install it from a
self-contained wheel package, it will need the libpq library at runtime
(usually distributed in a
relies on the host OS to find the library if the library is installed in a
standard location there is usually no problem; if the library is in a
non-standard location you will have to tell Psycopg how to find it,
which is OS-dependent (for instance setting a suitable
LD_LIBRARY_PATH on Linux).
The libpq header files used to compile
psycopg2 should match the
version of the library linked at runtime. If you get errors about missing
or mismatching libraries when importing
psycopg2 check (e.g. using
ldd) if the module
psycopg2/_psycopg.so is linked to the
Whatever version of libpq
psycopg2 is compiled with, it will be
possible to connect to PostgreSQL servers of any supported version: just
install the most recent libpq version or the most practical, without
trying to match it to the version of the PostgreSQL server you will have
to connect to.
If you have less standard requirements such as:
creating a debug build,
using pg_config not in the
then take a look at the
Some of the options available in
setup.cfg are also available as command
line arguments of the
build_ext sub-command. For instance you can specify
an alternate pg_config location using:
$ python setup.py build_ext --pg-config /path/to/pg_config build
python setup.py build_ext --help to get a list of the options
Creating a debug build¶
In case of problems, Psycopg can be configured to emit detailed debug messages, which can be very useful for diagnostics and to report a bug. In order to create a debug package:
Download and unpack the Psycopg source package (the
setup.cfgfile adding the
PSYCOPG_DEBUGflag to the
Compile and install the package.
$ export PSYCOPG_DEBUG=1
Run your program (making sure that the
psycopg2package imported is the one you just compiled and not e.g. the system one): you will have a copious stream of informations printed on stderr.
Non-standard Python Implementation¶
psycopg2 package is the current mature implementation of the adapter: it
is a C extension and as such it is only compatible with CPython. If you want
to use Psycopg on a different Python implementation (PyPy, Jython, IronPython)
there is a couple of alternative:
a Ctypes port, but it is not as mature as the C implementation yet and it is not as feature-complete;
a CFFI port which is currently more used and reported more efficient on PyPy, but please be careful of its version numbers because they are not aligned to the official psycopg2 ones and some features may differ.
Running the test suite¶
psycopg2 is installed you can run the test suite to verify it is
working correctly. From the source directory, you can run:
$ python -c "import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose
The tests run against a database called
psycopg2_test on UNIX socket and
the standard port. You can configure a different database to run the test by
setting the environment variables:
The database should already exist before running the tests.
If you still have problems¶
Try the following. In order:
Read again the Build prerequisites.
Read the FAQ.
psycopg2your error message. Especially useful the week after the release of a new OS X version.
Write to the Mailing List.
If you think that you have discovered a bug, test failure or missing feature please raise a ticket in the bug tracker.
Complain on your blog or on Twitter that
psycopg2is the worst package ever and about the quality time you have wasted figuring out the correct
ARCHFLAGS. Especially useful from the Starbucks near you.