https://github.com/psycopg/psycopg
New generation PostgreSQL database adapter for the Python programming language
https://github.com/psycopg/psycopg
database development driver postgresql python
Last synced: 6 months ago
JSON representation
New generation PostgreSQL database adapter for the Python programming language
- Host: GitHub
- URL: https://github.com/psycopg/psycopg
- Owner: psycopg
- License: lgpl-3.0
- Created: 2020-03-15T04:15:53.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-05-13T16:15:31.000Z (6 months ago)
- Last Synced: 2025-05-14T08:04:44.927Z (6 months ago)
- Topics: database, development, driver, postgresql, python
- Language: Python
- Homepage: https://www.psycopg.org/psycopg3/
- Size: 6.53 MB
- Stars: 1,945
- Watchers: 25
- Forks: 184
- Open Issues: 45
-
Metadata Files:
- Readme: README.rst
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
Awesome Lists containing this project
- best-of-python - GitHub - 8% open · ⏱️ 19.10.2025): (Database Clients)
- stars - psycopg/psycopg - New generation PostgreSQL database adapter for the Python programming language (Python)
- stars - psycopg/psycopg - New generation PostgreSQL database adapter for the Python programming language (Python)
README
Psycopg 3 -- PostgreSQL database adapter for Python
===================================================
Psycopg 3 is a modern implementation of a PostgreSQL adapter for Python.
Installation
------------
Quick version::
pip install --upgrade pip # upgrade pip to at least 20.3
pip install "psycopg[binary,pool]" # install binary dependencies
For further information about installation please check `the documentation`__.
.. __: https://www.psycopg.org/psycopg3/docs/basic/install.html
.. _Hacking:
Hacking
-------
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.
.. __: https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
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.
.. __: https://www.psycopg.org/psycopg3/docs/basic/install.html#local-installation
.. __: https://www.psycopg.org/psycopg3/docs/advanced/pool.html
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
pip install -e "./psycopg[dev,test]" # for the base Python package
pip install -e ./psycopg_pool # for the connection pool
pip install ./psycopg_c # for the C speedup module
.. __: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
Please add ``--config-settings editable_mode=strict`` to the ``pip install -e``
above if you experience `editable mode broken`__.
.. __: https://github.com/pypa/setuptools/issues/3557
Now hack away! You can run the tests using::
psql -c 'create database psycopg_test'
export PSYCOPG_TEST_DSN="dbname=psycopg_test"
pytest
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.
.. __: https://pre-commit.com/
Cross-compiling
---------------
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.
.. __: https://github.com/linkedin/shiv