Windows环境Docker部署Django项目时Psycopg2安装失败问题

核心原因 #

Docker容器是独立的隔离环境，本地Windows系统的pg_config路径配置对容器无效。Psycopg2（或psycopg-binary）安装失败，本质是容器内缺少编译依赖或依赖配置错误。

1. 修改Dockerfile，添加系统依赖 #

在构建Python镜像时，先安装PostgreSQL相关的编译依赖（以Debian/Ubuntu系镜像为例）：

FROM python:3.10-slim

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

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

2. 调整requirements.txt的依赖配置 #

• 方案一：使用psycopg-binary（推荐，无需编译）
  直接在requirements.txt中写入：

  psycopg-binary>=2.9.0
  # 其他依赖...
  

  psycopg-binary包含预编译的二进制文件，无需依赖系统编译工具，且Django代码中import psycopg2的写法完全兼容，不需要修改代码。

• 方案二：使用原生psycopg2
  确保Dockerfile已安装上述系统依赖后，requirements.txt中写入：

  psycopg2>=2.9.0
  # 其他依赖...
  

3. 验证docker-compose.yml配置 #

确保数据库服务使用官方PostgreSQL镜像，且web服务依赖db服务：

version: '3.8'

services:
  web:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/mydb  # 匹配db服务的配置

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data/

volumes:
  postgres_data:

4. 错误排查要点 #

• 若日志提示pg_config executable not found：说明容器内未安装libpq-dev，检查Dockerfile中的apt-get install步骤是否执行。
• 若日志提示编译失败（如缺少头文件）：确认已安装gcc和python3-dev。
• 若提示找不到psycopg2包：检查requirements.txt是否正确写入psycopg-binary，且Dockerfile中pip install步骤无报错。

内容的提问来源于stack exchange，提问作者Mbakop Dimitri