Django Docker构建时psycopg2安装失败问题求助

问题背景 #

执行docker build -t myimage .构建Django镜像时，Dockerfile中RUN pip install -r /app/requirements.txt --no-cache-dir命令在下载psycopg2-2.9.3.tar.gz环节抛出编译错误，尽管requirements.txt中仅声明了psycopg2-binary，未添加psycopg2。

requirements.txt片段 #

...
dj-database-url==0.5.0
Django==3.2.7
django-filter==21.1
django-formset-js-improved==0.5.0.2
django-heroku==0.3.1
psycopg2-binary
python-decouple==3.5
...

错误信息 #

Downloading pytz-2022.2.1-py2.py3-none-any.whl (500 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 500.6/500.6 kB 2.6 MB/s eta 0:00:00
Collecting psycopg2
  Downloading psycopg2-2.9.3.tar.gz (380 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 380.6/380.6 kB 2.7 MB/s eta 0:00:00
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'error'
  error: subprocess-exited-with-error

  × python setup.py egg_info did not run successfully.
  │ exit code: 1
  ╰─> [23 lines of output]
      running egg_info
      creating /tmp/pip-pip-egg-info-383i9hb2/psycopg2.egg-info
      writing /tmp/pip-pip-egg-info-383i9hb2/psycopg2.egg-info/PKG-INFO
      writing dependency_links to /tmp/pip-pip-egg-info-383i9hb2/psycopg2.egg-info/dependency_links.txt
      writing top-level names to /tmp/pip-pip-egg-info-383i9hb2/psycopg2.egg-info/top_level.txt
      writing manifest file '/tmp/pip-pip-egg-info-383i9hb2/psycopg2.egg-info/SOURCES.txt'

      Error: pg_config executable not found.

      pg_config is required to build psycopg2 from source.  Please add the directory
      containing pg_config to the $PATH or specify the full executable path with the
      option:

          python setup.py build_ext --pg-config /path/to/pg_config build ...

      or with the pg_config option in 'setup.cfg'.

      If you prefer to avoid building psycopg2 from source, please install the PyPI
      'psycopg2-binary' package instead.

      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.
The command '/bin/sh -c pip install -r /app/requirements.txt --no-cache-dir' returned a non-zero code: 1

原Dockerfile内容 #

FROM python:3.8.13-slim-buster
WORKDIR /app
COPY ./my_app ./

RUN pip install --upgrade pip --no-cache-dir

RUN pip install -r /app/requirements.txt --no-cache-dir

CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]
# CMD ["gunicorn", "main_app.wsgi:application", "--bind"]

问题原因 #

报错核心：django-heroku等依赖包隐式依赖了psycopg2，pip会自动拉取该依赖的源码进行编译。而python:slim-buster镜像为精简体积，未包含pg_config等PostgreSQL编译依赖，导致源码编译失败。

解决方案 #

方案1：安装系统编译依赖，支持psycopg2源码编译 #

在Dockerfile中添加编译依赖安装步骤，确保psycopg2可正常编译：

FROM python:3.8.13-slim-buster
WORKDIR /app
COPY ./my_app ./

# 安装psycopg2编译所需系统依赖，安装后清理apt缓存减小镜像体积
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --upgrade pip --no-cache-dir

RUN pip install -r /app/requirements.txt --no-cache-dir

CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

方案2：强制用psycopg2-binary替代psycopg2 #

修改requirements.txt，让pip将psycopg2的依赖请求替换为预编译的psycopg2-binary：

...
dj-database-url==0.5.0
Django==3.2.7
django-filter==21.1
django-formset-js-improved==0.5.0.2
django-heroku==0.3.1
# 强制替换psycopg2为psycopg2-binary
psycopg2-binary
psycopg2==psycopg2-binary
python-decouple==3.5
...

方案3：移除不必要的依赖包 #

如果项目未使用django-heroku，直接将其从requirements.txt中删除，即可消除对psycopg2的隐式依赖。

内容的提问来源于stack exchange，提问作者Destiny Franks