离线安装python环境必须在外网用pip download --recursive递归下载完整依赖树,严格匹配平台标签和python版本,并在内网用--no-index与--find-links配合安装。

能离线装,但必须在外网提前把“整棵树”一次性扒干净,否则进内网就卡在某个依赖上动不了。
pip download 是唯一靠谱的起点
别用 pip install --download(已废弃),也别手动一个一个找 .whl。真正能递归拉下全部依赖(包括子依赖、孙依赖)的只有 pip download。
- 它会解析
requirements.txt里每个包的setup.py或pyproject.toml,自动识别所有层级依赖 - 默认只下载兼容当前平台和 Python 版本的
.whl(比如numpy-1.26.4-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl),不会混入 Windows 或 aarch64 的包 - 如果目标环境是 CentOS 7 + Python 3.9,那外网打包机也得是同版本,否则下载的包可能安装失败或运行时报
ImportError: cannot import name '...' from '...'
--no-index 和 --find-links 必须成对出现
进内网后执行安装时,--no-index 禁用 PyPI 是铁律;但光禁用没用,你还得告诉 pip “去哪找包”,这就是 --find-links 的作用。
- 命令形如:
pip install --no-index --find-links=./offline_pkgs -r requirements.txt -
--find-links指向的目录必须包含所有.whl(或.tar.gz),且不能嵌套子目录——pip 不会递归扫描 - 如果漏了
--find-links,哪怕包都在当前目录,pip 也会报Could not find a version that satisfies the requirement xxx - 不加
--force-reinstall也没关系,pip 默认会跳过已满足的包;但如果你要覆盖旧版本(比如降级),就得加上
常见踩坑点:平台标识、缓存、路径权限
看似简单三步,实际一半失败都出在这几个细节上。
-
pip download在外网执行时,若没加--platform和--python-version,可能下错轮子(wheel)——比如给 CentOS 下了 macOS 的.whl,进内网直接报is not a supported wheel on this platform -
--no-cache-dir建议始终带上,避免 pip 从本地缓存拼凑出不完整依赖树 - 内网机器上执行
pip install时,确保当前用户对./offline_pkgs有读权限;用sudo pip install很容易因权限隔离导致找不到包 - 如果
requirements.txt里有-e git+https://...这类 VCS 依赖,pip download无法处理,必须提前转成固定 commit 的.whl或删掉
最麻烦的不是命令记不住,而是依赖树太深时,pip download 下载完你以为齐了,结果进内网一装,发现某个包内部硬编码调用了 pkg_resources.get_distribution(),而它依赖的 setuptools 版本又和当前环境不兼容——这种问题只能靠外网环境尽量贴近生产来压测。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











