uv默认仅安装匹配当前平台的二进制wheel,严格按platform_tag和abi_tag筛选,跳过源码包;跨平台预下载需显式指定--python-platform,否则离线安装将因平台不兼容失败。

uv 默认只安装兼容当前平台的二进制 wheel
uv 在安装包时,会严格按 platform_tag 和 abi_tag 匹配 wheel 文件,比如 numpy-1.26.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 这类文件,只有在目标系统满足 cp312 + manylinux2014_x86_64 时才会被选中。它不会尝试安装 win_amd64 或 macosx_12_0_arm64 的 wheel,哪怕本地缓存里有。
这和 pip 的行为一致,但 uv 更激进:它默认跳过所有需要编译的源码包(.tar.gz),除非显式启用 --build 或配置 UV_BUILD=1。所以如果你看到 error: No version found for xxx on this platform,大概率是 wheel 不匹配,而不是网络问题。
跨平台预下载 wheel 需要显式指定 --python-platform
你在 macOS 上为 Linux 生产环境准备离线包时,不能直接跑 uv pip install -r requirements.txt——它只会下 macOS 的 wheel。必须加参数锁定目标平台:
uv pip install -r requirements.txt --python-platform manylinux2024_x86_64uv pip install numpy --python-platform manylinux2014_aarch64- 平台标识必须准确,常见值见
uv python list --platforms输出
漏掉这个参数,uv.lock 里记录的 wheel 哈希和平台信息就和目标机器不一致,离线安装时会报 incompatible platform 错误。
立即学习“Python免费学习笔记(深入)”;
uv cache prune 会清理未被引用的 wheel 文件
uv 的全局缓存(~/.cache/uv)不是“下多少存多少”,而是按使用痕迹自动管理。当你用不同平台参数反复安装依赖,缓存里会积累多套 wheel;但执行 uv cache prune 后,只有最近一次 uv.lock 或虚拟环境里实际用到的 wheel 会被保留,其余全删。
这意味着:
- 离线打包前,务必先用目标平台参数完整走一遍
uv pip compile+uv pip install,确保所需 wheel 已下载并被引用 - 不要手动删
~/.cache/uv/archive下的文件——可能破坏哈希校验,导致后续uv sync失败 -
uv cache info可查看当前缓存中各平台 wheel 的数量和大小
源码包编译失败时,uv 不会自动 fallback 到其他 wheel
有些包(如 cryptography)只提供源码分发或有限平台的 wheel。当 uv 找不到匹配 wheel 且禁用了构建(默认行为),它直接报错退出,不会像 pip 那样尝试降级版本或换轮子。
解决方法只有两个:
- 加
--build允许编译:uv pip install cryptography --build - 提前下载好对应平台的 wheel 并放入本地 index(需配合
--find-links和--no-deps控制)
注意:--build 要求目标机器装了 rustc、gcc 等编译工具链——这在多数离线生产环境里不可行,所以**预下载 wheel 比临时编译更可靠**。


















