Installation#
In short, if you use one of the supported systems, run:
pip install --upgrade pip pip install "psycopg[binary]"
and you should be ready to start. Read further for alternative ways to install.
Note
Fun fact: there is no psycopg3
package, only psycopg
!
Supported systems#
The Psycopg version documented here has official and tested support for:
Python: from version 3.10 to 3.14
Python 3.8 and 3.9 are supported before Psycopg 3.3
Python 3.7 is supported before Psycopg 3.2
Python 3.6 is supported before Psycopg 3.1
PyPy: from version 3.10 to 3.11
PyPy 3.9 is supported before Psycopg 3.3
Note: Only the pure Python installation is currently supported.
PostgreSQL: from version 10 to 18
Note: PostgreSQL currently supported release are actively tested in the CI. Out-of-support releases are supported on a best-effort basis.
OS: Linux, macOS, Windows
Pip: 20.3 or newer
The tests to verify the supported systems run in Github workflows: anything that is not tested there is not officially supported. This includes:
Unofficial Python distributions such as Conda;
Alternative PostgreSQL implementation;
Other platforms such as BSD or Solaris.
If you use an unsupported system, things might work (because, for instance, the database may use the same wire protocol as PostgreSQL) but we cannot guarantee the correct working or a smooth ride.
Binary installation#
The quickest way to start developing with Psycopg 3 is to install the binary packages by running:
pip install "psycopg[binary]"
This will install a self-contained package with all the libraries needed. If you are coming from Psycopg 2, this is the equivalent of installing the psycopg2-binary
package.
See also
Did Psycopg 3 install ok? Great! You can now move on to the basic module usage to learn how it works.
Keep on reading if the above method didn’t work and you need a different way to install Psycopg 3.
For further information about the differences between the packages see pq module implementations.
If your platform is not supported, or if the libpq packaged is not suitable, you should proceed to a local installation or a pure Python installation.
Note
Binary packages are produced on a best-effort basis; the supported platforms depend on the CI runners available to build the packages. This means that:
binary packages for a new version of Python are made available once the runners used for the build support it. You can check the psycopg-binary PyPI files to verify whether your platform is supported;
the libpq version included in the binary packages depends on the version available on the runners. You can use the
psycopg.pq.version()
function and__build_version__
constant to infer the features available.
Local installation#
A “Local installation” results in a performing and maintainable library. The library will include the speed-up C module and will be linked to the system libraries (libpq
, libssl
…) so that system upgrade of libraries will upgrade the libraries used by Psycopg 3 too. This is the preferred way to install Psycopg for a production site.
In order to perform a local installation you need some prerequisites:
a C compiler,
Python development headers (e.g. the
python3-dev
package).PostgreSQL client development headers (e.g. the
libpq-dev
package).The pg_config program available in the
PATH
.
You must be able to troubleshoot an extension build, for instance you must be able to read your compiler’s error message. If you are not, please don’t try this and use the Binary installation instead.
If your build prerequisites are in place you can run:
pip install "psycopg[c]"
This will install a self-contained package with all the libraries needed. If you are coming from Psycopg 2, this is the equivalent of installing the psycopg2
package, both in terms of build requirements and system dependencies at runtime.
Warning
The local installation is not supported by PyPy.
Pure Python installation#
If you simply install:
pip install psycopg
without [c]
or [binary]
extras you will obtain a pure Python implementation. This is particularly handy for debugging and hacking.
Warning
The pure Python installation is much slower than the Binary installation or Local installation. It is likely sufficient for local developments or small tasks but, for production loads, you might want to install one of the speed-up extensions too.
In order to use the pure Python installation you will need the libpq
PostgreSQL client library installed on your client (which will be imported dynamically via ctypes
); for example on Debian systems you will probably need:
sudo apt install libpq5
If you are not able to fulfill this requirement please use a Binary installation, which packages its own copy of the libpq
.
Note
The libpq
is the client library also used by psql, the PostgreSQL command line client, to connect to the database. On most systems, installing psql will install the libpq
too as a dependency.
Installing the connection pool#
The Psycopg connection pools are distributed in a separate package from the psycopg
package itself, in order to allow a different release cycle.
In order to use the pool you must install the pool
extra, using pip install "psycopg[pool]"
, or install the psycopg_pool
package separately, which would allow to specify the release to install more precisely.
Handling dependencies#
If you need to specify your project dependencies (for instance in a requirements.txt
file, setup.py
, pyproject.toml
dependencies…) you should probably specify one of the following:
If your project is a library, add a dependency on
psycopg
. This will make sure that your library will have thepsycopg
package with the right interface and leaves the possibility of choosing a specific implementation to the end user of your library.If your project is a final application (e.g. a service running on a server) you can require a specific implementation, for instance
psycopg[c]
, after you have made sure that the prerequisites are met (e.g. the depending libraries and tools are installed in the host machine).
In both cases you can specify which version of Psycopg to use using requirement specifiers.
If you want to make sure that a specific implementation is used you can specify the PSYCOPG_IMPL
environment variable: importing the library will fail if the implementation specified is not available. See pq module implementations.