如何在python:3-slim Docker镜像中安装mysqlclient且避免镜像臃肿

问题背景 #

使用python:3.12-slim镜像执行RUN pip install mysqlclient时出现构建错误，核心原因是缺少pkg-config和MySQL/MariaDB开发依赖。直接安装完整构建依赖会导致镜像体积暴涨至700MB，即使清理后仍超过500MB，且构建耗时过长。

错误关键输出片段：

/bin/sh: 1: pkg-config: not found
Exception: Can not find valid pkg-config name.
Specify MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS env vars manually

初始Dockerfile：

FROM python:3.12-slim

RUN pip install mysqlclient

解决方案 #

方案1：使用预编译wheel（最推荐） #

mysqlclient针对Debian环境提供了预编译wheel包，无需编译即可安装，彻底避免依赖构建工具。

修改后的Dockerfile：

FROM python:3.12-slim

# 仅安装运行时必需的共享库
RUN apt-get update && apt-get install -y --no-install-recommends \
    libmysqlclient21 \
    && rm -rf /var/lib/apt/lists/*

RUN pip install mysqlclient

• libmysqlclient21是mysqlclient运行时依赖的共享库，体积极小
• 清理apt缓存进一步压缩镜像体积，最终镜像可控制在200MB左右，构建速度极快

方案2：精简构建依赖并彻底清理 #

若必须从源码编译（如特定版本无预编译wheel），可最小化安装构建依赖，编译完成后彻底清除所有冗余文件：

FROM python:3.12-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    pkg-config \
    default-libmysqlclient-dev \
    build-essential \
    && pip install mysqlclient \
    && apt-get purge -y --auto-remove \
    pkg-config \
    default-libmysqlclient-dev \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

• --no-install-recommends避免安装不必要的依赖包
• --auto-remove自动清除构建依赖的关联冗余包，比手动purge更彻底
• 最后删除apt缓存目录，最大程度压缩镜像

方案3：多阶段构建（极致精简） #

通过多阶段构建隔离构建环境与运行环境，最终镜像仅保留运行时必需文件：

# 构建阶段：安装编译依赖并编译mysqlclient
FROM python:3.12-slim AS builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    pkg-config \
    default-libmysqlclient-dev \
    build-essential

RUN pip install --user mysqlclient

# 最终阶段：仅复制运行时所需内容
FROM python:3.12-slim

# 安装运行时依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    libmysqlclient21 \
    && rm -rf /var/lib/apt/lists/*

# 从构建阶段复制已安装的mysqlclient到最终镜像
COPY --from=builder /root/.local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages

• 构建阶段的所有编译依赖不会进入最终镜像，最终镜像体积达到极致精简

内容的提问来源于stack exchange，提问作者Alastair McCormack