Installation¶
Psycopg is a PostgreSQL adapter for the Python programming language. It is a wrapper for the libpq, the official PostgreSQL client library.
Quick Install¶
For most operating systems, the quickest way to install Psycopg is using the wheel package available on PyPI:
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 like pip install -U pip ).
You may then import the psycopg2 package, as usual:
psycopg vs psycopg-binary¶
The psycopg2-binary package is meant for beginners to start playing with Python and PostgreSQL without the need to meet the build requirements.
If you are the maintainer of a published package depending on psycopg2 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, 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.
The psycopg2 wheel package comes packaged, among the others, with its own 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 package.
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.:
which can be specified in your requirements.txt files too, e.g. use:
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 .
Prerequisites¶
The current psycopg2 implementation supports:
Python versions from 3.6 to 3.11
PostgreSQL server versions from 7.4 to 15
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.
Build prerequisites¶
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:
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 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 :
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:
or, from the directory containing the source code:
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 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 right libpq.so .
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:
using pg_config not in the PATH ,
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:
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 (the .tar.gz package).
Edit the setup.cfg file adding the PSYCOPG_DEBUG flag to the define option.
Set the PSYCOPG_DEBUG environment variable:
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.
Non-standard Python Implementation¶
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 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¶
Once psycopg2 is installed you can run the test suite to verify it is working correctly. From the source directory, you can run:
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:
Google for psycopg2 your error message. Especially useful the week after the release of a new OS X version.
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 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.
Name already in use
psycopg2 / doc / src / install.rst
- Go to file T
- Go to line L
- Copy path
- Copy permalink
12 contributors
Users who have contributed to this file
- Open with Desktop
- View raw
- Copy raw contents Copy raw contents
Copy raw contents
Copy raw contents
Psycopg is a PostgreSQL adapter for the Python programming language. It is a wrapper for the libpq, the official PostgreSQL client library.
For most operating systems, the quickest way to install Psycopg is using the wheel package available on PyPI:
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 :program:`pip` (you can upgrade it using something like pip install -U pip ).
You may then import the psycopg2 package, as usual:
psycopg vs psycopg-binary
The psycopg2-binary package is meant for beginners to start playing with Python and PostgreSQL without the need to meet the build requirements.
If you are the maintainer of a published package depending on !psycopg2 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, 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.
The !psycopg2 wheel package comes packaged, among the others, with its own 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, :command:`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 package.
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 :command:`pip` —no-binary option, e.g.:
which can be specified in your :file:`requirements.txt` files too, e.g. use:
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 :ref:`build prerequisites <build-prerequisites>` .
The current !psycopg2 implementation supports:
- Python versions from 3.6 to 3.11
- PostgreSQL server versions from 7.4 to 15
- PostgreSQL client library version from 9.1
Not all the psycopg2 versions support all the supported Python versions.
Please see the :ref:`release notes <news>` 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:
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 :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` :
You only need :program:`pg_config` to compile !psycopg2, not for its regular usage.
Once everything is in place it’s just a matter of running the standard:
or, from the directory containing the source code:
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 Psycopg how to find it, which is OS-dependent (for instance setting a suitable :envvar:`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 :program:`ldd` ) if the module psycopg2/_psycopg.so is linked to the right libpq.so .
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 :ref:`debug build <debug-build>` ,
- using :program:`pg_config` not in the :envvar:`PATH` ,
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` location using:
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:
-
and unpack the Psycopg source package (the .tar.gz package).
- Edit the setup.cfg file adding the PSYCOPG_DEBUG flag to the define option. the package.
- Set the :envvar:`PSYCOPG_DEBUG` environment variable:
- 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.
Non-standard Python Implementation
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 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
Once !psycopg2 is installed you can run the test suite to verify it is working correctly. From the source directory, you can run:
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:
Introduction — Psycopg 2.7.7 documentation
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.
Prerequisites
The current psycopg2 implementation supports:
- Python 2 versions from 2.6 to 2.7
- Python 3 versions from 3.2 to 3.7
- PostgreSQL server versions from 7.4 to 10
- PostgreSQL client library version from 9.1
Build prerequisites
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:
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 :
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:
or, from the directory containing the source code:
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).
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 .
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.
Binary install from PyPI
psycopg2 is also 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, not requiring the above build or runtime prerequisites.
The -binary package is meant for beginners to start playing with Python and PostgreSQL without the need to meet the build requirements. If you are the maintainer of a publish package depending on psycopg2 you shouldn’t use psycopg2-binary as a module dependency. For production use you are advised to use the source distribution.
Make sure to use an up-to-date version of pip (you can upgrade it using something like pip install -U pip ), then you can run:
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.
The psycopg2 wheel package comes packaged, among the others, with its own 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.
Disabling wheel packages for Psycopg 2.7
In version 2.7.x, pip install psycopg2 would have tried to install the wheel binary package of Psycopg. Because of the problems the wheel package have displayed, psycopg2-binary has become a separate package, and from 2.8 it has become the only way to install the binary package.
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.:
which can be specified in your requirements.txt files too, e.g. use:
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 .
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:
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:
- 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:
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:
How to install psycopg2 on windows 7
I have tried pip install psycopg2 and following errors i got:
Then I tried using easy_install by downloading the .exe file from Stickpole and I got following errors :
But when I again tried to install through pip I am getting a new message that its already there :
Then I thought ok I should try to import and then I got this error:
Now I am not able to understand what to do. Thanks
Edit 1: I have also added my PostgreSQL path to system path variables
7 Answers 7
The correct answer was given by Craig Ringer, I am just adding this because I came to know that we should first check which version of 64 bit or 32bit Python installed on our system. If you have 32 bit version of Python and if you will try to install 64bit, then you will get the above error on importing. For checking the version:
and you will get an output like this:
Download the pre-packaged binary release of psycopg2 for Windows rather than compiling it yourself. It’s a pain to compile on Windows. This is explained in the install documentation for psycopg2.
You might need to remove your half-installed attempts.
Choose the appropriate version from this page:
Right click and select copy link address
Back at home, use easy_install <<Paste URL Here>>
Freeze your new requirements: pip freeze > requirements.txt
Now that psycopg is in PyPI (as of March 2017 it appears), just fire up a command prompt with administrator privileges and install like so:
If you don’t have pip installed, follow the instructions here to do that first: https://stackoverflow.com/a/12476379/2540707
pip install psycopg2-binary
This worked for me
Step 1: Compilers Installation and configuration
Before do anything, install or upgrade the Setuptools Python package. It contain compatibility improvements and add automatic use of compilers:
pip install —upgrade setuptools
Step 2: Download and install PostgreSQL
Before you continue to install python packages inside you virtualenvs download postgres itself. It contains files that are needed when compiling the psycopg2 python package. Just use the PostgreSQL installer(version 10 for example).
Important: add the postgres C:\Program Files\PostgreSQL\10\bin folder to your path. It contains the .dll needed for psycopg2.