怎么批量下载Python依赖包并制作离线安装源
详细讲解在无外网环境下如何批量下载Python项目全部依赖包,处理跨平台与架构兼容性,并基于本地目录或内网HTTP服务制作高效离线安装源。
在企业内网专网、生产隔离集群或安全隔离区(DMZ)等无互联网接入的环境中,部署 Python 应用无法直接通过 pip install 联网拉取依赖。制作离线安装源的核心路径分为两步:首先在一台与目标机系统架构兼容的联网机器上,使用 pip download 命令将清单内的所有主依赖及二级传递依赖完整批量下载为 Wheel(.whl)安装包;随后将包文件导入隔离环境,通过 --no-index --find-links 指定本地目录直接安装,或启动轻量 HTTP 服务搭建局域网共享安装源。
一、整体操作流程与前期准备
离线安装并非简单地拷贝几个第三方的 .whl 文件。Python 生态中的大多数库都会依赖其他底层库,例如安装 requests 必须同时安装 urllib3、certifi、charset_normalizer 和 idna。若缺少传递依赖,离线安装便会因找不到依赖项而中断。因此,完整的流程包含依赖导出、全量拉取、介质传输与离线配置四个阶段。
在开始下载前,需要先明确目标项目依赖清单。通常由项目现有的 requirements.txt 提供,或者在开发环境中通过命令生成:
# 在运行中的测试环境导出全部依赖
pip freeze > requirements.txt
如果当前开发环境安装了许多与项目无关的工具包,建议先创建一个独立的干净虚拟环境,仅安装项目实际运行需要的核心库,再次导出,以避免下载大量多余的包。
二、使用 pip download 批量下载依赖包
pip download 是官方提供的专门用于预先拉取包文件的工具。它不仅下载指定的顶层库,还会自动解析并下载该库依赖的所有关联组件。
1. 联网机与离线机系统完全一致(同构环境)
如果联网机器和目标内网机器运行相同版本的操作系统、CPU 架构(例如均为 x86_64 的 CentOS 7.9)以及相同小版本的 Python,下载最为简单直接:
# 创建存放依赖包的目录
mkdir -p ./offline_packages
# 批量下载 requirements.txt 中定义的所有依赖及其关联子包
pip download -r requirements.txt -d ./offline_packages
执行完成后,查看 ./offline_packages 目录,可以看到包含全部依赖的 .whl 文件和部分源码压缩包(.tar.gz)。
内网目标机器上的初始 Python 环境可能非常精简,甚至没有升级安装基础构建模块。强烈建议在下载业务依赖时,把构建基础工具一并下载备用:
pip download pip setuptools wheel -d ./offline_packages
2. 跨平台与跨架构批量下载(异构环境)
很多时候开发人员使用的是 macOS 或 Windows 电脑,而内网服务器是 Linux(如 x86_64 或 aarch64)。如果在 Windows 上直接执行简单的 pip download,默认会下载 Windows 专用的 wheel 文件或需要本地 C 编译器构建的源码包,这些包拷贝到 Linux 上将无法安装。
针对跨环境下载,必须向 pip download 传递明确的目标平台约束参数:
pip download \
--platform manylinux2014_x86_64 \
--python-version 310 \
--implementation cp \
--abi cp310 \
--only-binary=:all: \
-r requirements.txt \
-d ./offline_packages
参数的具体含义如下:
--platform manylinux2014_x86_64:指定目标系统的平台标识符。对于主流 Linux x86_64 服务器,常用的兼容标准是manylinux2014_x86_64或manylinux_2_17_x86_64。如果是 ARM 架构服务器,则指定manylinux2014_aarch64。--python-version 310:指定目标机器运行的 Python 版本(如 Python 3.10 写作 310 或 3.10)。--implementation cp:指定 Python 解释器实现,cp代表标准的 CPython。--abi cp310:指定应用二进制接口(Application Binary Interface)版本。--only-binary=:all::关键选项。跨平台下载时本地无法编译目标平台的 C 扩展源码包,因此该选项强制 pip 只下载官方预编译好的二进制.whl文件,严禁回退到.tar.gz源码包。
三、制作并部署离线安装源的两种方案
将全部依赖文件拷贝到隔离的内网目标主机后,可根据单机使用还是内网多机共享,采用不同的离线源形式。
方案一:本地目录直接安装(最轻量、推荐单机使用)
如果只是为单台物理机、虚拟机或制作 Docker 镜像,直接利用文件系统路径作为源是最简单且零维护成本的选择。
将包含所有 .whl 文件的目录(例如 /opt/offline_packages)和 requirements.txt 拷贝至内网目标机,执行以下安装命令:
pip install --no-index --find-links=/opt/offline_packages -r requirements.txt
这里有两个参数是保障离线安装成功的关键:
--no-index:严禁联网查询。告诉 pip 彻底忽略任何远程默认索引(如 pypi.org)。若不加此参数,pip 在解析依赖时仍会尝试连接外网,在无网环境下会导致长时间的网络连接超时报错。--find-links=/opt/offline_packages:指定从本地指定目录中寻找与候选包匹配的文件,支持绝对路径或相对路径。
方案二:构建内网 HTTP 简易源(适合多节点局域网)
当内网有数十台机器需要安装相同的依赖时,将包复制到每台机器非常低效。此时可以在内网中选择一台通用机器(如 192.168.1.100)搭建轻量 HTTP 服务。
第一步:在源服务器上启动 HTTP 服务
将依赖包目录存放在 /data/pypi/packages,使用 Python 内置的 http.server 模块启动文件共享服务:
# 进入包目录所在路径
cd /data/pypi/packages
# 启动简易 HTTP 文件服务器(绑定 8080 端口)
python3 -m http.server 8080
第二步:在内网客户端执行离线安装
在同局域网的其他节点上,直接将 --find-links 指向该 HTTP 地址:
pip install --no-index --find-links=http://192.168.1.100:8080/ -r requirements.txt
第三步:固化客户端全局配置(可选)
若希望客户端在使用 pip install 包名 时无需每次输入长参数,可修改客户端用户主目录下的 pip 配置文件(Linux/macOS 为 ~/.pip/pip.conf,Windows 为 %APPDATA%\pip\pip.ini):
[global]
no-index = true
find-links = http://192.168.1.100:8080/
trusted-host = 192.168.1.100
配置完成后,在客户端直接输入 pip install -r requirements.txt 便会自动从内网 HTTP 源拉取,不会触发任何外网连接。
四、常见问题排查与注意事项
1. 离线安装时报错:Could not find a version that satisfies the requirement
出现该报错主要有两种原因:
- 缺少传递依赖包:在联网机下载时,某些底层依赖已经存在于联网机全局环境中,导致
pip download认为无需重复拉取。解决方法是使用干净的虚拟环境重新执行pip download。 - Wheel 文件与离线机环境不匹配:例如下载的是
cp310(Python 3.10)的包,而离线机安装的是 Python 3.8;或者下载的是x86_64架构,离线机是aarch64。在离线机上运行python3 -V和uname -m仔细核对。
2. 离线安装时报错:Failed to build ... 或 error: command 'gcc' failed
这是因为下载的依赖包中混入了 .tar.gz 格式的源码包(Source Distribution),而在安装时 pip 会尝试调用本地系统的 C/C++ 编译器就地编译。如果内网机器缺少 gcc、make 或头文件,安装就会崩溃。
解决方法:在联网机重新执行下载,强制指定 --only-binary=:all: 下载预先编译好的 wheel。对于某些极少数官方不提供对应系统二进制 wheel 的特殊包,必须在同构的联网机上先执行 pip wheel 包名 构建出 wheel 文件后,再传输至内网。
3. 如何验证离线源是否完整可用
在正式导入生产环境前,可以在离线机(或拔掉网线的测试机)上创建一个全新的空虚拟环境进行整体验证:
# 创建隔离的测试虚拟环境
python3 -m venv test_env
source test_env/bin/activate
# 执行离线完整安装测试
pip install --no-index --find-links=/opt/offline_packages -r requirements.txt
# 测试核心模块是否能正常导入
python3 -c "import requests; print('依赖验证成功')"
如果无报错并顺利打印结果,说明制作的离线安装包集合完整、匹配正确,可以投入内网生产使用。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













