使用 uv 进行离线安装包操作,核心思路是利用 uv pip compile 锁定依赖树并导出为 .txt 文件,随后在目标机器上使用 uv pip install --requirement 配合本地缓存或 wheel 包进行安装。具体做法是:在有网络的环境中运行 uv pip compile requirements.in -o requirements.txt 生成精确版本列表,接着用 uv pip install --only-binary :all: -r requirements.txt -d ./packages 将所有依赖下载为 wheel 文件到指定目录;最后在离线环境中执行 uv pip install --no-index --find-links ./packages -r requirements.txt 即可完成安装。

如何生成包含所有依赖的离线包列表
在有网络的环境下,首先需要确定你的项目依赖,通常是一个 requirements.in 文件或直接在命令行指定包名。uv 的优势在于它会自动解析传递依赖(transitive dependencies),你不需要手动去查找子依赖。通过 uv pip compile 命令,你可以得到一个 requirements.txt 文件,其中包含了主依赖及其所有子依赖的确切版本号。这一步确保了依赖树的完整性和一致性,避免了“在我机器上能跑”的问题。

uv pip compile requirements.in -o requirements.txt uv pip install --only-binary :all: -r requirements.txt -d ./offline_packages
上述代码首先编译依赖树。然后,uv pip install 命令中的 --only-binary :all: 参数强制只下载预编译的二进制包(wheel),跳过源码包,这能显著加快下载速度并减少离线安装时的编译需求。-d ./offline_packages 指定了下载文件的存储目录。执行完毕后,./offline_packages 目录下将包含所有需要的 .whl 文件。
如何在无网络环境中完成安装
将生成的 requirements.txt 和 ./offline_packages 目录拷贝到离线服务器后,安装过程变得非常简单。关键在于告诉 uv 不要尝试连接 PyPI,而是从本地目录查找包。使用 --no-index 禁用索引源,并使用 --find-links 指向本地包目录。这样 uv 会像访问一个私有的 PyPI 镜像一样处理本地文件,自动解决依赖关系并完成安装。

uv pip install --no-index --find-links ./offline_packages -r requirements.txt
这条命令会在离线环境中解析 requirements.txt,并从 ./offline_packages 中拉取对应的 wheel 文件进行安装。如果环境中有多个 Python 版本,可以指定 --python-version 以确保兼容性。整个过程无需联网,且由于 uv 的高效性,安装速度通常远快于传统的 pip。
当依赖冲突时 uv 如何处理
在离线场景中,依赖冲突往往源于不同环境下的依赖树差异。例如,如果在有网环境编译时使用了特定版本的库,而离线环境的系统库提供了不同版本的同名库,可能会引发冲突。uv 在处理冲突时会优先遵循 requirements.txt 中锁定的版本。如果本地 ./offline_packages 中缺少某个必需版本,或者版本不匹配,uv 会报错并指出缺失或冲突的具体包。此时,你需要回到有网环境,检查 requirements.in 是否过于宽松,重新编译并更新 requirements.txt 和本地包目录,确保离线包与锁定文件完全一致。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











