Psycopg3 Binary and Django 4.2 Installation Quick Tip

One of Django 4.2's major features is support for Psycopg 3, the new implementation of the popular PostgreSQL adapter for Python. It is a replacement for Psycopg 2 that adds async support, better performance, and more all-around adaptability.

Recently, while updating to Django 4.2 and Psycopg 3, I came across a small quirk that devoured about an hour of my life. Here's hoping this article saves you that time.

Psycopg ships with a binary version that is great for getting started quickly. In the past, I would install it as follows:

(.venv) $ python -m pip install psycopg2-binary==2.9.5

So I naively assumed that for Psycopg 3 I could do the same. And indeed if you run the command below it does install the binary packages.

(.venv) $ python -m pip install psycopg-binary==3.1.8

The problem is that this will cause your deployment to fail. Psycopg 3 separates out the binary files now so you also need to install Psycopg 3 itself.

(.venv) $ python -m pip install psycopg==3.1.8

Or, if you follow the official documents, you can install both with one command:

(.venv) $ python -m pip install "psycopg[binary]"

So that's the quick tip. Use the newer installation method. And make sure to check that your virtual environment--via either pip freeze or python -m pip freeze > requirements.txt when creating a requirements.txt file--contains both psycopg==3.1.8 and psycopg-binary==3.1.8.