Docker容器中用Poetry安装Python项目后模块找不到问题求助

以下是针对问题的具体排查步骤和解决方案：

1. 验证Poetry配置是否生效 #

先确认virtualenvs.create的配置确实被设置为false：

poetry config virtualenvs.create

如果输出不是false，说明Dockerfile里的配置命令执行顺序有误——必须在poetry install之前执行poetry config virtualenvs.create false，否则配置不会对本次安装生效。

2. 检查Python路径一致性 #

即使容器内只有一个Python版本，也要确认Poetry关联的Python和你运行的Python是同一个：

# 查看Poetry使用的Python路径
poetry run which python
# 查看当前shell使用的Python路径
which python

如果两者路径不同，说明Poetry安装时绑定了其他Python环境（比如用pipx安装Poetry时使用的Python），这时候需要重新安装Poetry，确保它使用系统默认的Python：

pip uninstall poetry -y
pip install poetry==1.2.1

3. 对比依赖安装路径与Python的sys.path #

检查Poetry安装的依赖是否在Python的模块搜索路径中：

# 查看Poetry环境下的sys.path
poetry run python -c "import sys; print('\n'.join(sys.path))"
# 查看普通Python环境下的sys.path
python -c "import sys; print('\n'.join(sys.path))"

如果Poetry安装的依赖目录（通常是/usr/local/lib/pythonX.X/site-packages或用户目录下的site-packages）不在普通Python的sys.path里，需要设置PYTHONPATH环境变量，比如在Dockerfile中添加：

ENV PYTHONPATH="/usr/local/lib/python3.10/site-packages:${PYTHONPATH}"

（替换成你实际的依赖安装路径）

4. 检查Dockerfile中的用户切换问题 #

如果你的Dockerfile中使用了USER命令切换到非root用户，要确保依赖是在切换用户之前安装的：

# 错误：先切换用户再安装依赖，依赖会被安装到用户私有目录，可能不在系统Python路径中
RUN useradd -m appuser && USER appuser
RUN poetry install

# 正确：先安装依赖，再切换用户
RUN poetry install --no-dev
RUN useradd -m appuser && USER appuser

如果必须在用户切换后安装依赖，需要用poetry install --user，同时设置PYTHONPATH包含用户的site-packages目录：

ENV PYTHONPATH="/home/appuser/.local/lib/python3.10/site-packages:${PYTHONPATH}"

5. 验证依赖是否真的被安装 #

直接查看已安装的包列表，确认依赖是否存在：

# 用Poetry查看
poetry show django
# 用pip查看（如果安装到系统环境，pip应该能查到）
pip list | grep django

如果pip list里看不到依赖，说明Poetry没有将依赖安装到系统pip管理的路径，这时候可以尝试删除poetry.lock重新生成，再执行安装：

rm poetry.lock
poetry lock
poetry install --no-dev

参考Dockerfile示例 #

以下是一个正确配置的Dockerfile示例，可作为参考：

FROM python:3.10-slim

WORKDIR /app

# 安装指定版本的Poetry
RUN pip install poetry==1.2.1

# 核心配置：禁用虚拟环境
RUN poetry config virtualenvs.create false

# 复制依赖配置文件
COPY pyproject.toml poetry.lock ./

# 安装生产依赖（--no-dev排除开发依赖，--no-root不安装项目本身）
RUN poetry install --no-dev --no-root

# 复制项目代码
COPY . .

# 运行服务（以Django为例）
CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

内容的提问来源于stack exchange，提问作者Radu M.