使用python:3.11 Docker镜像时内置test模块无法找到的问题咨询

问题描述 #

原始多阶段构建Dockerfile #

# syntax=docker/dockerfile:1

FROM python:3.11 as DEP_BUILDER
ENV PYTHONFAULTHANDLER=1 \
    PYTHONUNBUFFERED=1 \
    PYTHONHASHSEED=random \
    PIP_NO_CACHE_DIR=off \
    PIP_DISABLE_PIP_VERSION_CHECK=on \
    PIP_DEFAULT_TIMEOUT=100 \
    POETRY_CACHE_DIR='/var/cache/pypoetry' \
    POETRY_HOME='/usr/local'
ARG POETRY_VERSION=1.8.3
WORKDIR /venv
RUN apt-get update && apt-get install -y curl
RUN curl -sSL https://install.python-poetry.org | python3 -
COPY pyproject.toml /venv/
RUN python -m venv .venv
RUN . .venv/bin/activate && \
    poetry config virtualenvs.in-project true && \
    poetry install --no-interaction --no-ansi --with dev


FROM python:3.11
WORKDIR /server
COPY /app /server/app
COPY /tests /server/tests
COPY --from=DEP_BUILDER /venv/.venv ./.venv
ENV PATH="/server/.venv/bin:$PATH"
CMD ./.venv/bin/python3 -m pytest tests

运行错误信息 #

Attaching to app-1
app-1  | ImportError while loading conftest '/server/tests/conftest.py'.
app-1  | tests/conftest.py:10: in <module>
app-1  |     from test.support.os_helper import EnvironmentVarGuard
app-1  | E   ModuleNotFoundError: No module named 'test'
app-1 exited with code 4

排查步骤 #

为验证是否为虚拟环境问题，修改第二阶段构建逻辑：

FROM python:3.11
WORKDIR /server
COPY /app /server/app
COPY /tests /server/tests
COPY --from=DEP_BUILDER /venv/.venv/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
CMD python -m pytest

但错误依旧，确认Docker镜像中完全缺失test模块。

用户疑问 #

官方Python Docker镜像是否不含该模块？是否存在包含该模块的Python Docker镜像？

解决方案 #

官方镜像说明 #

官方Python Docker镜像（如python:3.11）默认会裁剪掉test这类非核心标准库模块，目的是大幅缩小镜像体积。官方并未提供预构建的、包含所有标准库模块的镜像，但可以通过以下方式补全test模块：

解决方法1：安装系统包补全模块 #

在第二阶段的Dockerfile中，添加安装python3-test包的命令（基于Debian/Ubuntu系统的镜像）：

FROM python:3.11
WORKDIR /server
# 安装包含test模块的系统包，安装后清理apt缓存减小体积
RUN apt-get update && apt-get install -y --no-install-recommends python3-test \
    && rm -rf /var/lib/apt/lists/*
COPY /app /server/app
COPY /tests /server/tests
COPY --from=DEP_BUILDER /venv/.venv ./.venv
ENV PATH="/server/.venv/bin:$PATH"
CMD ./.venv/bin/python3 -m pytest tests

解决方法2：使用未裁剪的Python环境（备选） #

如果需要完整的Python标准库，也可以基于官方镜像手动构建未裁剪版本，或使用第三方维护的完整Python镜像，但官方渠道推荐使用方法1来按需补全模块，避免镜像体积过大。

内容的提问来源于stack exchange，提问作者Aitor Martin