psycopg2/doc/src/install.rst

Introduction
============

.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>

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:

..
    NOTE: keep consistent with setup.py and the /features/ page.

- Python 2 versions from 2.6 to 2.7
- Python 3 versions from 3.1 to 3.5
- PostgreSQL server versions from 7.4 to 9.5
- PostgreSQL client library version from 9.1

.. _PostgreSQL: http://www.postgresql.org/
.. _Python: http://www.python.org/
.. _libpq: http://www.postgresql.org/docs/current/static/libpq.html
.. _CPython: http://en.wikipedia.org/wiki/CPython
.. _Ctypes: http://docs.python.org/library/ctypes.html
.. __: https://github.com/mvantellingen/psycopg2-ctypes


.. 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 :ref:`install Psycopg from a package
<install-from-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 :ref:`module usage <usage>`
avoid bothering with the gory details.

.. note::

    Regardless of the way `!psycopg2` is installed, at runtime it will need to
    use the libpq_ library. `!psycopg2` relies on the host OS to find the
    library file (usually ``libpq.so`` or ``libpq.dll``): 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 :envvar:`LD_LIBRARY_PATH` on Linux).



.. _install-from-package:

Install from a package
----------------------

.. index::
    pair: Install; Linux

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


.. index::
    pair: Install; Mac OS X

**Mac OS X**
    Psycopg is available as a `fink package`__ in the *unstable* tree: you may
    install it with::

        fink install psycopg2-py27

    .. __: http://pdb.finkproject.org/pdb/package.php/psycopg2-py27

    The library is also available on `MacPorts`__ try::

         sudo port install py27-psycopg2

    .. __: http://www.macports.org/


.. index::
    pair: Install; Windows

**Microsoft Windows**
    There are two options to install a precompiled `psycopg2` package under windows:

    **Option 1:** Using `pip`__ (Included in python 2.7.9+ and python 3.4+)
    and a binary wheel package.  Launch windows' command prompt (`cmd.exe`)
    and execute the following command::
    
        pip install psycopg2

    .. __: https://pip.pypa.io/en/stable/installing/

    **Option 2:** Jason Erickson maintains a packaged `Windows port of Psycopg`__ with
    installation executable. Download. Double click. Done.

    .. __: http://www.stickpeople.com/projects/python/win-psycopg/



.. index::
    single: Install; from source

.. _install-from-source:

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.

.. _requirements:

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 :program:`pg_config` program: it is usually installed by the
  **libpq-dev** package but sometimes it is not in a :envvar:`PATH` directory.
  Having it in the :envvar:`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 :program:`pg_config`
  shipped with the right libpq version (usually
  ``/usr/lib/postgresql/X.Y/bin/``) and add it to the :envvar:`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
    :program:`ldd`) if the module ``psycopg2/_psycopg.so`` is linked to the
    right ``libpq.so``.



.. index::
    single: Install; from PyPI

.. _package-manager:

Use a Python package manager
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the above requirements are satisfied, you can use :program:`easy_install`,
:program:`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, :program:`virtualenv` (fully supported by recent Psycopg
versions), using different Python versions and other nuances.


.. index::
    single: setup.py
    single: setup.cfg

.. _source-package:

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 :ref:`debug build <debug-build>`,
- using :program:`pg_config` not in the :envvar:`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 :program:`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.

.. __: http://initd.org/psycopg/download/



.. index::
    single: tests

.. _test-suite:

Running the test suite
^^^^^^^^^^^^^^^^^^^^^^

The included ``Makefile`` allows to run all the tests included in the
distribution. Just run::

    make
    make check

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:

- :envvar:`PSYCOPG2_TESTDB`
- :envvar:`PSYCOPG2_TESTDB_HOST`
- :envvar:`PSYCOPG2_TESTDB_PORT`
- :envvar:`PSYCOPG2_TESTDB_USER`

The database should already exist before running the tests.



.. index::
    single: debug
    single: PSYCOPG_DEBUG

.. _debug-build:

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.

- :ref:`Compile and install <source-package>` the package.

- Set the :envvar:`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.

.. __: http://initd.org/psycopg/download/



.. _other-problems:

If you still have problems
--------------------------

Try the following. *In order:*

- Read again the :ref:`requirements <requirements>`.

- Read the :ref:`FAQ <faq-compile>`.

- 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
  :envvar:`ARCHFLAGS`. Especially useful from the Starbucks near you.

.. __: http://mail.postgresql.org/mj/mj_wwwusr/domain=postgresql.org?func=lists-long-full&extra=psycopg