Docker环境下Poetry run创建虚拟环境失败的原因与路径疑问

我有一个可成功执行poetry install并构建镜像的Dockerfile，内容如下：

FROM python:3.11-slim-bookworm as base
RUN apt-get update && \
    apt-get install -y iputils-ping curl && \
    rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir poetry==1.8.2


FROM base as dependencies
WORKDIR /app
COPY pyproject.toml poetry.lock /app/
RUN  poetry install --no-interaction


FROM dependencies as application
WORKDIR /app
COPY llm_fast/*.py llm_fast/
COPY llm_fast/llmlib llm_fast/llmlib/
COPY resources resources/
COPY .env ./

RUN useradd -ms /bin/bash llmuser; chown -R llmuser /home/llmuser

当通过Docker Compose执行以下命令时，出现错误：

poetry --venv /home/llmuser/ run python -m gunicorn -w 1 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8086 llm_fast.vectorize:app

错误信息：

Creating virtualenv llm-fast-9TtSrW0h-py3.11 in /.cache/pypoetry/virtualenvs
virtualenv: error: argument dest: the destination . is not write-able at /

疑问：

• 为何poetry run会尝试创建虚拟环境？
• 为何它要在/目录创建，而非应用所在的/app目录或用户主目录/home/llmuser？

1. poetry run尝试创建虚拟环境的原因 #

• 在dependencies阶段执行poetry install时，Poetry默认会为root用户创建并使用一个虚拟环境。如果运行时切换到llmuser，由于用户上下文和权限不同，Poetry无法识别这个已存在的虚拟环境，因此会触发重新创建流程。
• 命令中--venv /home/llmuser/的用法错误：Poetry的--venv参数需要指定完整的虚拟环境目录路径（比如/home/llmuser/.cache/pypoetry/virtualenvs/llm-fast-xxx），而非父目录。错误的参数导致Poetry无法定位到已有的虚拟环境，进而尝试新建。

2. 在/目录创建虚拟环境的原因 #

• 如果运行时未切换到llmuser，或llmuser的HOME环境变量未正确配置，Poetry会沿用root用户的默认缓存路径/.cache/pypoetry/virtualenvs。但llmuser没有/目录的写入权限，因此报错。
• 即便切换到了llmuser，若未设置POETRY_CACHE_DIR环境变量，Poetry可能仍会尝试使用全局缓存路径，而非/home/llmuser/.cache。

方案1：修复--venv参数并匹配环境 #

找到dependencies阶段生成的虚拟环境完整路径（通常在/.cache/pypoetry/virtualenvs/下），在命令中指定该路径：

poetry --venv /.cache/pypoetry/virtualenvs/llm-fast-9TtSrW0h-py3.11 run python -m gunicorn ...

注：该方案依赖镜像构建时生成的虚拟环境名称，稳定性较差，不推荐长期使用。

方案2：在Dockerfile中配置固定虚拟环境路径 #

修改dependencies阶段的命令，指定虚拟环境路径到/home/llmuser并配置权限：

FROM base as dependencies
WORKDIR /app
COPY pyproject.toml poetry.lock /app/
# 配置Poetry虚拟环境路径并安装依赖
RUN poetry config virtualenvs.path /home/llmuser/.cache/pypoetry/virtualenvs \
    && poetry install --no-interaction
# 给llmuser赋予缓存目录权限
RUN mkdir -p /home/llmuser/.cache/pypoetry && chown -R llmuser /home/llmuser

在application阶段切换到llmuser：

FROM dependencies as application
WORKDIR /app
# 复制代码文件...
USER llmuser

此时运行命令无需指定--venv，Poetry会自动识别/home/llmuser下的虚拟环境：

poetry run python -m gunicorn ...

方案3：直接调用虚拟环境中的Python解释器 #

跳过poetry run，直接使用虚拟环境内的Python执行命令：

/home/llmuser/.cache/pypoetry/virtualenvs/llm-fast-9TtSrW0h-py3.11/bin/python -m gunicorn ...

为避免硬编码虚拟环境名称，可在构建时创建软链接：

RUN ln -s $(poetry run which python) /usr/local/bin/app-python

运行时直接使用软链接：

app-python -m gunicorn ...

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