Docker构建FastAPI镜像时pip install触发RuntimeError求助

问题背景 #

• 环境：MacOS，Docker 2.2.0.3，引擎版本19.03.5
• 执行构建命令：docker build --no-cache -t name:latest .
• 核心问题：所有涉及pip install的步骤均触发RuntimeError: can't start new thread错误，移除pip操作后构建流程正常。

已尝试的无效操作 #

• 更换多种pip调用方式（pip3 install、pip install --upgrade pip、python3 -m pip install）
• 尝试安装单个包或从requirements.txt批量安装
• 替换基础镜像为python:3.9-slim
• 添加构建参数--network=host、--shm-size 10g
• 关闭Docker Buildkit

解决方案 #

1. 升级Docker版本 #

当前使用的Docker版本过于陈旧，这类线程创建失败的问题已在新版本中修复。直接升级到最新稳定版Docker Desktop for Mac后重新执行构建。

2. 调整Docker资源分配 #

打开Docker Desktop偏好设置，增加容器可使用的CPU和内存资源（建议内存调整至4GB以上），资源不足可能导致线程创建失败。

3. 强制pip使用单线程安装 #

修改pip安装命令，禁用多线程相关操作：

# 使用--no-threads参数（适配多数pip版本）
RUN python3 -m pip install --no-threads --no-cache-dir -r ./requirements.txt

# 或添加更多限制参数，避免线程创建
RUN python3 -m pip install --no-cache-dir --no-build-isolation --disable-pip-version-check -r ./requirements.txt

4. 本地预构建虚拟环境后复制到容器 #

跳过容器内的pip安装步骤，在本地提前构建包含依赖的虚拟环境：

1. 本地执行命令：

python3.9 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
deactivate

2. 修改Dockerfile：

# syntax=docker/dockerfile:1
FROM python:3.9
LABEL maintainer="X Y <X@Y.com>"

# 直接复制本地预构建的虚拟环境
COPY ./venv /venv
ENV PATH="/venv/bin:$PATH"

COPY ./app /app
WORKDIR /app/

COPY ./start.sh /start.sh
RUN chmod +x /start.sh

COPY ./gunicorn_conf.py /gunicorn_conf.py

COPY ./start-reload.sh /start-reload.sh
RUN chmod +x /start-reload.sh

ENV PYTHONPATH=/app

EXPOSE 8000

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