Docker运行Poetry镜像提示poetry not found问题排查与解决

架构老林

2026-8-30

问题根因

启动报错和Poetry路径配置没有关系，核心错误是初始Dockerfile中CMD指令的语法不符合规范。
Docker的CMD、ENTRYPOINT指令分两种执行格式：

exec格式（官方推荐）：传入标准JSON数组，数组元素之间必须用英文逗号分隔，每个命令参数单独作为一个数组元素，执行时不会经过shell解析
shell格式：直接传入命令字符串，执行时会自动通过/bin/sh -c包裹运行

你初始编写的CMD ["poetry" "-V"]漏掉了两个数组元素之间的英文逗号，Docker无法将其识别为合法的exec格式数组，会自动降级用shell格式解析整段内容，直接把[poetry当作要执行的命令名，最终触发not found报错。

逻辑验证

你通过全路径直接执行容器内Poetry命令可以正常返回版本号，已经证明Poetry安装流程、PATH环境变量配置都是正常的：

docker run -it test /opt/poetry/bin/poetry -V
Poetry version 1.1.13

后续修改为ENTRYPOINT [ "poetry" ] + CMD ["-V"]后容器能正常运行，本质是这次的JSON数组语法写对了（元素之间补了逗号），和你用ENTRYPOINT还是CMD没有直接关联——哪怕改回纯CMD写法，只要语法正确就能正常跑。

修正方案

如果要保留单CMD启动的写法，只需要补上缺失的逗号即可：

# 注意两个数组元素之间必须加英文逗号
CMD ["poetry", "-V"]

附两个镜像优化的小细节：

安装apt依赖时加上--no-install-recommends参数，安装完成后清理/var/lib/apt/lists/*缓存，可以有效缩小镜像体积
Poetry安装依赖时加上--no-root参数，避免不必要地将当前项目本身安装到site-packages中

修正语法后的完整可运行Dockerfile如下：

FROM python:3.9-slim-buster

ARG APP_PATH=/app
ARG PYTHON_VERSION=3.9
ARG POETRY_VERSION=1.1.13
ARG POETRY_HOME="/opt/poetry"

ENV PYTHONDONTWRITEBYTECODE 1 \
    PYTHONUNBUFFERED 1 \
    POETRY_VERSION=$POETRY_VERSION \
    POETRY_VIRTUALENVS_IN_PROJECT=true \
    POETRY_NO_INTERACTION=1 \
    POETRY_HOME=${POETRY_HOME}

ENV PATH="$POETRY_HOME/bin:$PATH"

RUN apt-get update \
    && apt-get install curl -y --no-install-recommends \
    && curl -sSL https://install.python-poetry.org | python - --version ${POETRY_VERSION} \
    && rm -rf /var/lib/apt/lists/*

WORKDIR $APP_PATH
COPY pyproject.toml poetry.lock $APP_PATH

RUN poetry config virtualenvs.create false \
    && poetry install --no-dev --no-interaction --no-ansi --no-root

CMD ["poetry", "-V"]

避坑提示：使用exec格式编写CMD/ENTRYPOINT时，必须保证JSON语法完全合规：所有引号使用英文双引号、数组元素之间用英文逗号分隔，否则Docker会自动降级到shell解析模式，触发类似的命令找不到报错。

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