Introduction — Psycopg 2.7.3.2 documentation

# Introduction

Psycopg is a PostgreSQL adapter for the Python programming language. It is a wrapper for the libpq, the official PostgreSQL client library.

The `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 an experimental porting of Psycopg for Ctypes, but it is not as mature as the C implementation yet.

The current `psycopg2` implementation supports:

- 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

## Binary install from PyPI

`psycopg2` is available on PyPI in the form of wheel 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 using:

    $ pip install psycopg2

Make sure to use an up-to-date version of pip (you can upgrade it using something like `pip install -U pip`)

Note

The binary packages come with their own versions of a few C libraries, among which `libpq` and `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 `psycopg2` from source if you want to maintain binary upgradeability.

Warning

Because the `psycopg` wheel package uses its own `libssl` binary, it is incompatible with other extension modules binding with `libssl` as well, for instance the Python `ssl` module: the result will likely be a segfault. If you need using both `psycopg2` and other libraries using `libssl` please install psycopg from source.

If you prefer to use the system libraries available on your client you can use the pip `--no-binary` option:

    $ pip install --no-binary psycopg2

which can be specified in your `requirements.txt` files too, e.g. use:

    psycopg2>=2.7,<2.8 --no-binary :all:

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.

## Install from source

You can download a copy of Psycopg source files from the Psycopg download page or from PyPI.

### Build prerequisites

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 `PATH` directory. Having it in the `PATH` greatly 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 `PATH`:

      $ 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

### Runtime requirements

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 `libpq.so` or `libpq.dll` file). `psycopg2` 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 `LD_LIBRARY_PATH` on Linux).

Note

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 right `libpq.so`.

Note

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.

### Non-standard builds

If you have less standard requirements such as:

- creating a debug build,
- using pg_config not in the `PATH`,
- supporting `mx.DateTime`,

then take a look at the `setup.cfg` file.

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

Use `python setup.py build_ext --help` to get a list of the options supported.

### 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.
- Edit the `setup.cfg` file adding the `PSYCOPG_DEBUG` flag to the `define` option.
- Compile and install the package.
- Set the `PSYCOPG_DEBUG` environment variable:

    $ export PSYCOPG_DEBUG=1

- Run your program (making sure that the `psycopg2` package 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.

## Running the test suite

Once `psycopg2` 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 `psycopg2_test` on UNIX socket and the standard port. You can configure a different database to run the test by setting the environment variables:

- `PSYCOPG2_TESTDB`
- `PSYCOPG2_TESTDB_HOST`
- `PSYCOPG2_TESTDB_PORT`
- `PSYCOPG2_TESTDB_USER`

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.
- Google for `psycopg2` your 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 `psycopg2` is the worst package ever and about the quality time you have wasted figuring out the correct `ARCHFLAGS`. Especially useful from the Starbucks near you.