离线无pip场景下python3 setup.py install安装相关问题

虚拟环境安装路径异常、手动复制包的相关说明 #

• 执行python3 setup.py install后包被安装到系统路径，核心原因是调用的解释器是系统全局Python，而非虚拟环境内的解释器，通常是未正确激活虚拟环境导致。
  正确安装前置操作：
  1. 执行source /helper/bin/activate激活目标虚拟环境
  2. 执行which python3校验返回值，必须为/helper/bin/python3才确认当前使用的是虚拟环境解释器
  3. 此时再执行源码安装命令，包会自动部署到/helper/lib/python3.8/site-packages路径，不会写入系统目录
• 直接复制/usr/local/lib/python3.8/dist-packages下内容到虚拟环境site-packages的操作不可行：
  1. dist-packages是Debian/Ubuntu系列系统Python专属的第三方包目录，和虚拟环境的包索引规则、元数据校验逻辑存在差异
  2. 执行setup.py install的部署动作不止复制源码：还会在对应bin目录生成可执行入口脚本、编译匹配当前CPU架构的C扩展二进制文件、写入依赖关联元数据，仅复制dist-packages下的内容会遗漏上述文件，直接导致模块缺失、运行报错
  3. 手动复制不会触发虚拟环境的包索引更新，部分包即使文件存在也无法被解释器识别

无setup.py类包（以zipp为例）的安装方法 #

• 首先明确：当前Python生态已普遍采用PEP 517/518规范打包，不再强制要求提供setup.py，多数新包的构建配置写在pyproject.toml中，没有setup.py属于正常情况，并非包损坏或缺少安装文件。
• 仅复制zipp.egg-info到site目录完全无法使用：.egg-info/.dist-info仅存储包的版本、依赖关系等元数据，不包含包运行所需的核心源码，只复制元数据没有任何作用。
• 离线无网络场景下的正确安装方式：
  1. 优先使用wheel包离线部署（适配所有格式的包，稳定性最高）
     提前在和嵌入式设备同Python版本、同CPU架构的有网环境中，执行命令下载目标包及全量依赖的wheel格式预编译包：

     # 示例：下载适配Python3.8、ARM64架构的包及所有依赖到offline_pkgs目录
     pip download 目标包名 -d ./offline_pkgs --platform linux_aarch64 --python-version 3.8 --implementation cp --abi cp38 --only-binary=:all:
     

     将整个offline_pkgs目录拷贝到离线环境后，无需联网，直接调用虚拟环境内的pip即可完成全量安装，不需要关注包是否带setup.py：

     /helper/bin/pip install --no-index --find-links=./offline_pkgs 目标包名
     

  2. 无pip可用时的纯Python包部署方案
     对于zipp这类不含C扩展的纯Python包，解压源码包后找到和包同名的核心源码目录（例如zipp解压后的zipp/文件夹，内含__init__.py等核心运行代码），将该源码目录、配套的.dist-info/.egg-info元数据文件夹一同复制到虚拟环境的site-packages目录下，即可正常导入使用。

注意：如果嵌入式设备为ARM等非x86架构，不要直接复制x86环境下编译的含C扩展的包，否则会触发CPU架构不兼容错误；纯Python包不受CPU架构影响，可以跨架构复制部署。

内容的提问来源于stack exchange，提问作者user1538798