Python wheel 包的本地缓存策略

pip反复下载同一wheel是因默认不复用已下载文件，其缓存仅作用于http响应而非wheel分发；解决方法是用–find-links指向本地wheel目录并配合–no-index和–no-deps。

pip install 时为什么反复下载同一个 wheel

因为 pip 默认不复用已下载的 wheel 文件，每次安装都会重新获取——哪怕你刚装过一模一样的版本。这不是 bug，是设计如此：pip 的缓存只对 http 响应生效，而 wheel 下载属于「构建后分发」环节，走的是单独的下载逻辑。

常见错误现象：pip install requests 执行两次，网络请求日志里出现两轮 Downloading requests-2.31.0-py3-none-any.whl；本地磁盘没有保留中间产物。

• 触发场景：CI 环境反复重装依赖、离线环境手动传包、多项目共用同一份依赖但没共享缓存
• 根本原因：pip 的 --find-links 和 --no-index 不自动启用本地 wheel 复用，它只管“从哪找”，不管“找过了要不要再找”
• 解决方向不是关掉网络，而是让 pip 明确知道“这个 wheel 我已经有，别下了”

怎么让 pip 优先用本地 wheel 缓存

核心是把 wheel 文件放进 pip 能主动扫描的缓存目录，并确保安装命令带上对应标记。pip 自带的 --find-links + --no-deps 组合容易误用，真正稳定的做法是用 --find-links 指向一个本地目录，再加 --trusted-host（如果用 http）和 --no-index 强制禁用 PyPI。

• 步骤一：把 wheel 文件统一丢进某个目录，比如 ./wheels/，支持子目录嵌套
• 步骤二：运行 pip install --find-links ./wheels/ --no-index --no-deps requests
• 注意：--no-deps 是关键——否则 pip 仍会尝试去 PyPI 拉依赖项；若需递归安装，得保证所有依赖 wheel 都在该目录下
• 路径必须是绝对路径或相对于当前工作目录的相对路径；~/wheels 这种写法在某些 shell 下不展开，建议用 $HOME/wheels

cache-dir 和 wheel-dir 的区别与误用风险

--cache-dir 控制的是 pip 内部 HTTP 缓存和构建临时文件位置，不影响 wheel 复用行为；--wheel-dir 是旧版参数，仅用于“把构建出的 wheel 存到哪”，不参与安装时的查找逻辑——这两个都不是你要找的“本地 wheel 缓存开关”。

立即学习“Python免费学习笔记（深入）”；

• 常见坑：pip install --cache-dir ./pip-cache requests 完全无效，cache-dir 不改变 wheel 下载策略
• 另一个坑：pip wheel --wheel-dir ./wheels requests 只生成 wheel，不自动注册为可安装源；必须配合 --find-links 才能被后续 install 命令感知
• 兼容性注意：python 3.12+ 中 --wheel-dir 已弃用，改用 --wheel 标志控制是否生成 wheel，但依然不解决复用问题

CI/CD 中稳定复用 wheel 的最小实践

在 gitHub Actions 或 gitlab CI 里，靠 pip cache 指令本身不能解决 wheel 复用，得把 wheel 构建和安装拆成两步，并显式上传/下载 wheel 包。

• 构建阶段：用 pip wheel --no-deps --wheel-dir ./dist -r requirements.txt 生成所有 wheel 到 ./dist/
• 缓存该目录（github Actions 用 actions/cache，key 包含 requirements.txt hash）
• 安装阶段：用 pip install --find-links ./dist --no-index --no-deps -r requirements.txt
• 额外提醒：如果 requirements.txt 含 git+ 或 path: 依赖，它们不会被打包成 wheel，需单独处理或排除

复杂点在于 wheel 名字包含平台标签（如 cp39-cp39-manylinux_2_17_x86_64），跨平台 CI 时得确认构建环境和目标环境 ABI 兼容，否则 pip 会跳过匹配失败的 wheel 并回退到源码安装。