Psycopg 3 is a modern implementation of a PostgreSQL adapter for Python.

Quick version:

pip install "psycopg[binary,pool]"

For further information about installation please check the documentation.

In order to work on the Psycopg source code, you must have the libpq PostgreSQL client library installed on the system. For instance, on Debian systems, you can obtain it by running:

sudo apt install libpq5

On macOS, run:

brew install libpq

On Windows you can use EnterpriseDB's installers to obtain libpq which is included in the Command Line Tools.

You can then clone this repository to develop Psycopg:

git clone https://github.com/psycopg/psycopg.git
cd psycopg

Please note that the repository contains the source code of several Python packages, which may have different requirements:

• The psycopg directory contains the pure python implementation of psycopg. The package has only a runtime dependency on the libpq, the PostgreSQL client library, which should be installed in your system.
• The psycopg_c directory contains an optimization module written in C/Cython. In order to build it you will need a few development tools: please look at Local installation in the docs for the details.
• The psycopg_pool directory contains the connection pools implementations. This is kept as a separate package to allow a different release cycle.

You can create a local virtualenv and install the packages in development mode, together with their development and testing requirements:

python -m venv .venv
source .venv/bin/activate

# Install the base Psycopg package in editable mode
pip install --config-settings editable_mode=strict -e "./psycopg[dev,test]"

# Install the connection pool package in editable mode
pip install --config-settings editable_mode=strict -e ./psycopg_pool

# Install the C speedup extension
pip install ./psycopg_c

The --config-settings editable_mode=strict will be probably required to work around the problem of the editable mode broken.

Now hack away! You can run the tests using:

psql -c 'create database psycopg_test'
export PSYCOPG_TEST_DSN="dbname=psycopg_test"
pytest

If some of the tests fail on your local host, it may be helpful to exclude the proxy, subprocess, and/or timing tests to get a clean test run, for example:

pytest  -m 'not proxy and not timing'

The project includes some pre-commit hooks to check that the code is valid according to the project coding convention. Please make sure to install them by running:

pre-commit install

This will allow to check lint errors before submitting merge requests, which will save you time and frustrations.

Please follow the conventional commits specification for your commit messages.

If your change may affect the performance, for instance in the code waiting for the network, the COPY, or the adaptation of the data, please measure it, comparing it with the master branch:

python tests/scripts/bench_compare.py --tree base=master --tree head=. \
    --check warn

This runs the micro-benchmarks of tests/scripts/benchmark.py on both trees and reports the differences: the time of different workloads, sync and async, how long the async event loop is blocked, the CPU used while idle, and the memory used by a large COPY. --check warn lists the measures worse than the base beyond the usual noise. Use --impl c to measure the C implementation (it builds the psycopg_c extension of each tree). Please report the results in your pull request. Run the scripts with --help for details; the tests/scripts/bench.yml workflow runs the same comparison on Linux, macOS and Windows: copy it to .github/workflows/ in a temporary commit to run the comparison on CI.

To use cross-platform zipapps created with shiv that include Psycopg as a dependency you must also have libpq installed. See the section above for install instructions.