构建Docker镜像时pip安装出现未知包哈希不匹配错误求助

架构老林

2026-6-16

Pip哈希不匹配错误显示“unknown package”的排查与解决

问题现象

构建Docker镜像执行pip install -r requirements.txt时触发哈希不匹配错误，且报错包显示为unknown package，具体错误输出如下：

2775.3 ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE. If you have updated the package versions, please update the hashes. Otherwise, examine the package contents carefully; someone may have tampered with them.  
2775.3     unknown package:
2775.3         Expected sha256 f083fc24912aa410be21fa16d157fed2055dab1cc4b6934a0e03cba69eb242b9
2775.3              Got        3efa059ccefefd80228c849800b5f4d1b8dcf25aac45213bf937fe75fe19a554

已尝试添加/移除--no-cache-dir、--verbose参数，更新pip，添加--trusted-host等操作，均未解决问题。使用Windows系统，未启用VPN。

Dockerfile

FROM public.ecr.aws/lambda/python:3.12

# Set pip configurations for better stability
ENV PIP_DEFAULT_TIMEOUT=500 \
    PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_NO_CACHE_DIR=1

# Copy requirements.txt
COPY requirements.txt ${LAMBDA_TASK_ROOT}

# Install the specified packages
RUN pip install -r requirements.txt --no-cache-dir

# For local testing.
EXPOSE 8000

# Set IS_USING_IMAGE_RUNTIME Environment Variable
ENV IS_USING_IMAGE_RUNTIME=True

# Copy all files in ./src
COPY src/* ${LAMBDA_TASK_ROOT}
COPY src/rag_app ${LAMBDA_TASK_ROOT}/rag_app
COPY src/data/vectorstore ${LAMBDA_TASK_ROOT}/data/vectorstore

requirements.txt

fastapi==0.115.4
langchain==0.3.7
langchain_community==0.3.5
langchain_core==0.3.15
langchain_huggingface==0.1.2
mangum==0.19.0
pydantic==2.9.2
uvicorn==0.32.0

排查与解决方法

1. 修复Windows换行符导致的解析异常

Windows默认使用CRLF换行符，而Linux容器内采用LF，pip读取requirements.txt时可能因换行符差异解析出无效内容，触发“unknown package”错误。

操作：
- 用VS Code打开requirements.txt，点击右下角的CRLF切换为LF，保存后重新构建镜像。
- 或在Dockerfile中添加换行符转换步骤，放在COPY requirements.txt之后、pip install之前：
```
RUN sed -i 's/\r$//' ${LAMBDA_TASK_ROOT}/requirements.txt
```

2. 更换PyPI镜像源并强制清理缓存

默认PyPI源可能存在传输不稳定导致包损坏，或容器内残留缓存干扰安装。

操作：修改Dockerfile中的pip install命令，替换为国内稳定镜像（如阿里云）：
```
RUN pip install -r requirements.txt --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/
```
同时执行docker build --no-cache .强制清理Docker构建缓存。

3. 定位哈希对应的依赖包

报错的哈希值可能来自直接依赖的间接依赖，pip无法识别包名。

操作：
1. 复制期望哈希值f083fc24912aa410be21fa16d157fed2055dab1cc4b6934a0e03cba69eb242b9，在PyPI官网搜索该哈希，找到对应的包和版本。
2. 在requirements.txt中明确指定该包的版本，避免版本漂移导致哈希不匹配。

4. 生成带哈希的requirements文件

直接生成包含所有依赖（含间接依赖）哈希的文件，确保安装时的一致性。

操作：在本地Windows环境下执行以下命令生成带哈希的requirements文件：
```
pip install pip-tools
pip-compile --generate-hashes requirements.txt
```
生成requirements.txt（或requirements.txt.lock）后，替换原文件并重新构建镜像。

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