如何利用pip download命令实现Python环境的离线迁移

离线迁移必须用 pip download 递归下载完整依赖树，需指定 --platform、--python-version 和 --only-binary=:all: 确保跨平台兼容；内网安装须配对使用 --no-index 和 --find-links，且 wheel 文件须平铺于指定目录。

能离线迁移，但必须在外网一次性把整个依赖树“扒干净”，漏一个依赖，进内网就卡住不动。

pip download 是唯一能递归拉全依赖的命令

别用已废弃的 pip install --download，也别手动去 PyPI 网站翻找 .whl 文件。只有 pip download 会真正解析 setup.py 或 pyproject.toml，自动下载目标包、它的直接依赖、子依赖、孙依赖……直到整棵树闭合。

• 默认只下兼容当前平台和 Python 版本的 wheel（比如 numpy-1.26.4-cp39-cp39-manylinux_2_17_x86_64.whl），不会混入 Windows 或 arm64 的包
• 如果目标环境是 CentOS 7 + Python 3.9，外网打包机最好也是同版本；否则可能装上却运行时报 ImportError: cannot import name 'xxx' from 'yyy'
• 对 requirements.txt 批量操作更稳妥：pip download -r requirements.txt -d ./offline_pkgs

--platform 和 --python-version 必须配 --only-binary=:all:

跨平台离线部署时，这是最常翻车的点。比如给国产 Linux 服务器（manylinux2014_x86_64）下载包，却在 macOS 上执行了没加参数的 pip download，结果下了一堆 macosx_10_15_x86_64 的 wheel，进内网直接报 is not a supported wheel on this platform。

• 必须同时指定：--platform=manylinux2014_x86_64 --python-version=3.11 --only-binary=:all:
• --only-binary=:all: 是强制项——源码包（.tar.gz）没法跨平台预编译，不加它，pip 可能混入无法安装的源码包
• 常见平台标识：win_amd64、manylinux2014_x86_64、macosx_10_15_x86_64、macosx_11_0_arm64

--no-index 和 --find-links 必须成对出现

进内网后，pip install 命令里这两个参数缺一不可。只写 --no-index，pip 会说找不到包；只写 --find-links，它仍会尝试连 PyPI，失败后才退回来找本地，浪费时间还可能干扰缓存。

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

• 正确写法：pip install --no-index --find-links=./offline_pkgs -r requirements.txt
• --find-links 指向的目录不能有子目录——pip 不会递归扫描 ./offline_pkgs/dep1/ 这类路径，所有 .whl 必须平铺在该目录下
• 确保当前用户对 ./offline_pkgs 有读权限；用 sudo pip install 容易因权限隔离导致 pip 找不到包
• 如果 requirements.txt 里含 -e git+https://... 这类 VCS 依赖，pip download 无法处理，必须提前删掉或转成固定 commit 的 wheel

依赖树太深时，靠 pip freeze 生成 requirements.txt 很危险

pip freeze > requirements.txt 会把当前环境中所有包都列出来，包括开发依赖、系统自带包（如 setuptools）、甚至被其他项目装上的冗余包。这会导致离线包体积暴增，还可能引入版本冲突。

• 推荐用 pipdeptree 构建精确依赖图：pip install pipdeptree，然后 pipdeptree --packages pandas,requests --freeze > full_reqs.txt
• 再用 pip download -r full_reqs.txt -d ./offline_pkgs --no-cache-dir，--no-cache-dir 能避免 pip 从本地缓存拼凑出不完整依赖树
• 装完后别急着用，建议在内网机器上跑一次 python -c "import pandas; print(pandas.__version__)"，验证是否真能 import

最容易被忽略的是隐式依赖：比如某个包内部硬编码调用了 pkg_resources.get_distribution()，而它依赖的 setuptools 版本又和当前环境不匹配——这种问题不会在安装时报错，只会在运行时突然崩掉。