Preface

Didn't we recently get the Docker setup for DjangoStarter working again?

Initially, the demo deployment was using SQLite, and it worked fine, but issues quickly arose when switching to PostgreSQL...

Error

After starting Docker, the app container throws an error

django.core.exceptions.ImproperlyConfigured: Error loading psycopg2 or psycopg module

Troubleshooting

At first, I thought the issue was either with installing the psycopg2 library or that dependencies from the python_builder stage weren't correctly copied to the final stage container. However, after adjusting a few things and retrying, it still didn’t work.

Next, I used python src/manage.py shell to enter the shell and tested whether the psycopg2 library could be imported.

>>> import psycopg2
Traceback (most recent call last):
  File "<console>", line 1, in <module>
  File "/project/.venv/lib/python3.11/site-packages/psycopg2/__init__.py", line 51, in <module>
    from psycopg2._psycopg import (                     # noqa
ImportError: libpq.so.5: cannot open shared object file: No such file or directory

Alright, experienced Docker users should have already spotted the issue—it’s related to the system environment.

Switching from the slim image to a standard Python image resolved the problem…

Solution

OK, now that the root cause has been identified, we can proceed to tackle it.

Using psycopg2-binary

The simplest way is to replace the psycopg2 library with psycopg2-binary, which is a pre-compiled psycopg2 package that doesn't require a compilation environment, making installation much more convenient.

Manually Installing the libpq Library

Since the libpq library is missing, let's install it within the Docker image.

I haven't tested this method yet; it's troublesome and not elegant.

Use Python 3.11 slim base image

FROM python:3.11-slim

Installing psycopg2 Dependencies

RUN apt-get update && apt-get install -y
libpq-dev
gcc
# Clear cache to reduce image size && apt-get clean
&& rm -rf /var/lib/apt/lists/*

## Different Python Base Images

Python images are based on the Debian system, using the latest stable version of Debian by default. You can also specify the version yourself; for example, `python3.11-slim-bookworm` indicates using Debian 12 ("bookworm") as the base image.

- The image built using the `python3.11-slim-bookworm` base image is 424MB in size, and the `python3.11-slim` base image produces the same size.
- Using the `python3.11` base image results in a size of 1.3GB, which is several times larger.

You can also opt for Alpine-based images, but they may come with more compatibility issues. I won’t bother with that—it’s mentally exhausting.
## Summary

Generally speaking, relying on slim images is perfectly fine. Since they are based on Debian, compatibility issues are rarely a concern.

Occasional minor problems are usually quite straightforward to resolve.

Alpine images, on the other hand, are a different story altogether and can be quite a handful...