Dockerfile中直接指定Poetry版本失败，求正确配置方法

问题场景 #

尝试在Dockerfile中直接指定Poetry版本而非通过构建参数传递，但执行镜像构建时出现安装错误。

原Dockerfile代码 #

# Base image for the Docker container.
ARG BASE_IMAGE=python:3.11.5-alpine3.18

# Specify the Poetry version directly in the Dockerfile.
ARG POETRY_VERSION=1.6.1

# Rest of your Dockerfile...

# System deps: install poetry with the specified version
RUN pip install "poetry==${POETRY_VERSION}"

报错信息 #

=> ERROR [2/8] RUN pip install "poetry=="                                                                                                                                                                                                                          1.5s 
------
 > [2/8] RUN pip install "poetry==":
#0 1.210 Collecting poetry==
#0 1.478   Could not find a version that satisfies the requirement poetry== (from versions: 0.1.0, 0.2.0, 0.3.0, 0.4.0, 0.4.0.post1, 0.4.1, 0.4.2, 0.5.0b1, 0.5.0b2, 0.5.0, 0.6.0, 0.6.1, 0.6.2, 0.6.3b1, 0.6.3b2, 0.6.3b3, 0.6.3b4, 0.6.3b5, 0.6.3b6, 0.6.3b7, 0.6.3, 0.6.4b1, 0.6.4, 0.6.5, 0.7.0b1, 0.7.0b2, 0.7.0b3, 0.7.0b4, 0.7.0, 0.7.1, 0.8.0a0, 0.8.0a1, 0.8.0a2, 0.8.0a3, 0.8.0a4, 0.8.0, 0.8.1a0, 0.8.1, 0.8.2, 0.8.3, 0.8.4, 0.8.5a0, 0.8.5, 0.8.6, 0.9.0a0, 0.9.0a1, 0.9.0a2, 0.9.0a3, 0.9.0, 0.9.1, 0.10.0a0, 0.10.0a1, 0.10.0a2, 0.10.0a3, 0.10.0, 0.10.1, 0.10.2, 0.10.3, 0.11.0a0, 0.11.0a1, 0.11.0a2, 0.11.0a3, 0.11.0a4, 0.11.0, 0.11.1, 0.11.2, 0.11.3, 0.11.4, 0.11.5, 0.12.0a0, 0.12.0a1, 0.12.0a2, 0.12.0a3, 0.12.0a4, 0.12.0a5, 0.12.0, 0.12.1, 0.12.2, 0.12.3, 0.12.4, 0.12.5, 0.12.6, 0.12.7, 0.12.8, 0.12.9, 0.12.10, 0.12.11, 0.12.12, 0.12.13, 0.12.14, 0.12.15, 0.12.16, 0.12.17, 1.0.0a0, 1.0.0a1, 1.0.0a2, 1.0.0a3, 1.0.0a4, 1.0.0a5, 1.0.0b1, 1.0.0b2, 1.0.0b3, 1.0.0b4, 1.0.0b5, 1.0.0b6, 1.0.0b7, 1.0.0b8, 1.0.0b9, 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6, 1.0.7, 1.0.8, 1.0.9, 1.0.10, 1.1.0a1, 1.1.0a2, 1.1.0a3, 1.1.0b1, 1.1.0b2, 1.1.0b3, 1.1.0b4, 1.1.0rc1, 1.1.0, 1.1.1, 1.1.2, 1.1.3, 1.1.4, 1.1.5, 1.1.6, 1.1.7, 1.1.8, 1.1.9, 1.1.10, 1.1.11, 1.1.12, 1.1.13, 1.1.14, 1.1.15, 1.2.0a1, 1.2.0a2)
#0 1.480 No matching distribution found for poetry==
------
failed to solve: executor failed running [/bin/sh -c pip install "poetry==$POETRY_VERSION"]: exit code: 1

错误原因 #

报错中显示poetry==，说明POETRY_VERSION变量未被正确解析，导致pip尝试安装无版本指定的poetry，自然找不到匹配包。核心问题是ARG指令的作用域限制：

• ARG变量仅在声明后到下一个FROM指令前的阶段有效，多阶段构建时跨阶段会失效
• 若RUN指令所在阶段未重新声明该ARG变量，变量会被视为未定义

解决方案 #

方案1：确保ARG与RUN处于同一构建阶段 #

将ARG POETRY_VERSION放在FROM指令之后，确保变量处于当前构建阶段的作用域内：

# Base image for the Docker container.
ARG BASE_IMAGE=python:3.11.5-alpine3.18
FROM ${BASE_IMAGE}

# 声明Poetry版本，确保在当前构建阶段生效
ARG POETRY_VERSION=1.6.1

# 安装指定版本的poetry
RUN pip install "poetry==${POETRY_VERSION}"

# Rest of your Dockerfile...

方案2：用ENV替代ARG（无需动态修改版本时） #

如果不需要在构建时通过--build-arg调整版本，直接用ENV声明变量，其作用域覆盖整个容器环境：

# Base image for the Docker container.
ARG BASE_IMAGE=python:3.11.5-alpine3.18
FROM ${BASE_IMAGE}

# 设置Poetry版本为环境变量
ENV POETRY_VERSION=1.6.1

# 安装指定版本的poetry
RUN pip install "poetry==${POETRY_VERSION}"

# Rest of your Dockerfile...

方案3：直接硬编码版本号（最简单方式） #

如果完全不需要动态指定版本，直接将版本号写入pip命令，避免变量解析问题：

# Base image for the Docker container.
ARG BASE_IMAGE=python:3.11.5-alpine3.18
FROM ${BASE_IMAGE}

# 直接安装指定版本的poetry
RUN pip install "poetry==1.6.1"

# Rest of your Dockerfile...

验证方法 #

构建时可添加RUN echo ${POETRY_VERSION}指令，确认变量是否被正确解析：

ARG BASE_IMAGE=python:3.11.5-alpine3.18
FROM ${BASE_IMAGE}
ARG POETRY_VERSION=1.6.1

RUN echo "待安装的Poetry版本：${POETRY_VERSION}"
RUN pip install "poetry==${POETRY_VERSION}"

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