Introduction - Psycopg 2.7.3 documentation
package is the current mature implementation of the adapter: it
is a C extension and as such it is only compatible with
. If you want
to use Psycopg on a different Python implementation (PyPy, Jython, IronPython)
there is an experimental
porting of Psycopg for Ctypes
, but it is not as
mature as the C implementation yet.
- Python 2 versions from 2.6 to 2.7
- Python 3 versions from 3.2 to 3.6
- PostgreSQL server versions from 7.4 to 9.6
- PostgreSQL client library version from 9.1
available on PyPI
in the form of
packages for the
most common platform (Linux, OSX, Windows): this should make you able to
install a binary version of the module including all the dependencies simply
$ pip install psycopg2
Make sure to use an up-to-date version of
(you can upgrade it
using something like
The binary packages come with their own versions of a few C libraries,
, which will be used regardless of other
libraries available on the client: upgrading the system libraries will not
upgrade the libraries used by
. Please build
source if you want to maintain binary upgradeability.
wheel package uses its own
binary, it is
incompatible with other extension modules binding with
for instance the Python
module: the result will likely be a
segfault. If you need using both
and other libraries using
install psycopg from source
If you prefer to use the system libraries available on your client you can use
$ pip install --no-binary psycopg2
which can be specified in your
files too, e.g. use:
psycopg2>=2.7,<2.8 --no-binary :all:
to use the last bugfix release of the
2.7 package, specifying to
always compile it from source. Of course in this case you will have to meet
These notes illustrate how to compile Psycopg on Linux. If you want to compile Psycopg on other platforms you may have to adjust some details accordingly.
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 . 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:
$ python setup.py build $ python setup.py install
Unless you compile
as a static library, or you install it from a
self-contained wheel package, it will need the
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 somehow Psycopg how to find it,
which is OS-dependent (for instance setting a suitable
The libpq header files used to compile
should match the
version of the library linked at runtime. If you get errors about missing
or mismatching libraries when importing
check (e.g. using
) if the module
is linked to the
Whatever version of libpq
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 ,
not in the
then take a look at the
Some of the options available in
are also available as command
line arguments of the
sub-command. For instance you can specify
$ python setup.py build_ext --pg-config /path/to/pg_config build
to get a list of the options
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.
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.
is installed you can run the test suite to verify it is
working correctly. You can run:
$ python -c "from psycopg2 import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose
The tests run against a database called
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.
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 .
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.