Introduction — Psycopg 2.5.2 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Psycopg 2.5.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.5 to 2.7
- Python 3 versions from 3.1 to 3.3
- PostgreSQL versions from 7.4 to 9.2

Note

`psycopg2` usually depends at runtime on the libpq dynamic library. However it can connect to PostgreSQL servers of any supported version, independently of the version of the libpq used: 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.

# Installation

If possible, and usually it is, please install Psycopg from a package available for your distribution or operating system.

Compiling from source is a very easy task, however `psycopg2` is a C extension module and as such it requires a few more things in place respect to a pure Python module. So, if you don’t have experience compiling Python extension packages, above all if you are a Windows or a Mac OS user, please use a pre-compiled package and go straight to the module usage avoid bothering with the gory details.

## Install from a package

Linux

  Psycopg is available already packaged in many Linux distributions: look for a package such as `python-psycopg2` using the package manager of your choice.

  On Debian, Ubuntu and other deb-based distributions you should just need:

      sudo apt-get install python-psycopg2

  to install the package with all its dependencies.

Mac OS X

  Psycopg is available as a fink package in the unstable tree: you may install it with:

      fink install psycopg2-py27

  The library is also available on MacPorts try:

      sudo port install py27-psycopg2

Microsoft Windows
  Jason Erickson maintains a packaged Windows port of Psycopg with installation executable. Download. Double click. Done.

## Install from source

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 to 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 it to compile and install `psycopg2`, not for its regular usage.

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`.

### Use a Python package manager

If the above requirements are satisfied, you can use easy_install, pip or whatever the Python package manager of the week:

    $ pip install psycopg2

Please refer to your package manager documentation about performing a local or global installation, virtualenv (fully supported by recent Psycopg versions), using different Python versions and other nuances.

### Use the source package

You can download a copy of Psycopg source files from the Psycopg download page. Once unpackaged, to compile and install the package you can run:

    $ python setup.py build
    $ sudo python setup.py install

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 version 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` 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 stdout.

## If you still have problems

Try the following. In order:

- Read again the requirements.
- 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.

### Navigation

- index
- modules |
- next |
- previous |
- Psycopg 2.5.2 documentation »