Pip离线安装本地依赖包完整教程（Windows+Linux，含参数详解）

在企业内网、物理隔离设备、无外网服务器等封闭环境中，无法直接通过 pip 联网安装 Python 依赖包，是几乎所有开发、运维都会遇到的头疼难题。很多同学离线部署踩坑：下载源码包离线要编译、子依赖缺失、Windows下载的包放到Linux无法使用、版本不匹配疯狂报错。本篇文章适配 Windows、Linux 双平台，手把手带你走通「联网导出→离线下载→文件迁移→本地离线安装」完整闭环，参数逐行讲解，附带可直接复制的跨平台bat脚本，零基础也能搞定隔离环境Python项目部署。

🎯本文适合哪些场景？

专为无外网、物理隔离、网络受限的 Python 环境部署编写，覆盖绝大多数企业真实落地场景：

✅内网业务部署：企业内网服务器、测试环境禁止外网访问，不能联网拉取依赖
✅涉密隔离环境：政府、国企、军工物理断网设备，Python项目上线交付
✅批量环境迁移：几十上百台服务器统一初始化Python环境，锁定版本批量同步
✅网络恶劣环境：PyPI官方源超时、下载慢、频繁断线，离线包实现稳定安装
✅版本固化交付：杜绝在线安装自动升级依赖，保证开发、测试、生产环境版本100%一致

📋整体流程总览（Windows/Linux通用）

⚠️最重要前置提醒：联网下载包的Python版本，必须和离线目标机器Python版本完全一致，否则大概率安装失败！

复制代码

【环境校验】确认联网机器与离线机器：系统一致 + Python版本完全一致
        ↓
【步骤1】导出项目依赖 → pip freeze > requirements.txt
        ↓
【步骤2】下载离线whl包 → pip download 获取全量依赖（必带仅二进制包参数）
        ↓
【步骤3】文件迁移 → 拷贝requirements.txt + offline_packages文件夹至离线机器
        ↓
【步骤4】离线安装 → Windows/Linux执行本地批量离线安装命令
        ↓
【步骤5】环境验证 → pip list 校验所有依赖安装成功

核心思想：同源环境下载完整whl包 → 完整迁移文件 → 纯本地不访问外网索引 → 校验结果。严格按照这套流程，可以避开99%离线安装报错。

1️⃣导出项目依赖清单

在可以联网、和目标环境版本对齐的机器上，进入你的项目根目录，执行命令导出全部已安装依赖+精准版本，生成requirements.txt：

复制代码

pip freeze > requirements.txt

💡小提示：如果只想导出本项目用到的依赖，不导出全部环境包，可以使用pipreqs工具，避免无关包被打包进离线包。

2️⃣批量下载全部离线whl包

根据清单下载主依赖+所有嵌套子依赖，一定要强制下载whl二进制包！千万不要下载tar.gz源码包，离线服务器大概率没有GCC编译环境，源码包几乎装不上。

参数解释：

-r requirements.txt：读取依赖清单，批量下载清单内所有包
-d ./offline_packages：所有whl包统一保存到此文件夹
--only-binary=:all:：核心参数，只下载二进制whl，拒绝源码包
-i 清华源地址：国内加速，解决官方源慢、超时
--platform 指定目标操作系统架构
--python-version Python版本，3.10写310，3.9写39

#基础版本
pip download -r requirements.txt -d ./offline_packages --only-binary=:all:

#【推荐国内使用｜清华镜像加速示例】
pip download -r requirements.txt -d ./offline_packages --platform win_amd64 --python-version 313 --only-binary=:all: -i https://pypi.tuna.tsinghua.edu.cn/simple

👉单独下载某一个包（补缺失依赖）

离线部署完成后，如果发现缺个别包，不需要全部重新下载，单独下载包+它的子依赖即可：

复制代码

#格式 pip download 包名 -d 保存目录 参数
pip download requests -d ./offline_packages --platform win_amd64 --python-version 313 --only-binary=:all: -i https://pypi.tuna.tsinghua.edu.cn/simple

📌常用平台标签对照表

目标机器环境	platform参数值
Linux x86_64 CentOS7+	manylinux2014_x86_64
Linux ARM64(aarch64鲲鹏服务器)	manylinux2014_aarch64
Windows 64位	win_amd64

3️⃣迁移文件到离线隔离机器

把两样东西完整拷贝到不能上网的服务器：

requirements.txt 依赖清单文件
offline_packages（整个whl包文件夹，不要只拷贝单个whl）

❗不要只复制单个whl文件，会丢失嵌套子依赖，出现大量ModuleNotFoundError

4️⃣离线机器执行批量安装

--no-index：重中之重！完全关闭pip外网请求，禁止访问pypi，全程本地读取

--find-links：告诉pip去哪里寻找whl包，会自动解析子依赖

复制代码

pip install --no-index --find-links=./offline_packages -r requirements.txt

单个whl包手动安装

⚠️注意：这种方式不会自动安装子依赖，只适合没有任何依赖的简单包！

复制代码

pip install ./offline_packages/xxx.whl

🚀实战脚本

Windows直接下载Linux平台whl（跨平台神器）很多小伙伴手上只有Windows开发机，但是要给内网Linux服务器做离线部署。不用换到Linux机器下载，下面bat脚本一键跨平台下载Linux x86_64的whl包。

新建文件命名：download_linux_wheels.bat

复制代码

@echo off
chcp 65001 >nul
echo ==============================================
echo Windows下跨平台下载 Linux x86_64 whl离线包
echo 目标平台: manylinux2014_x86_64
echo ==============================================
:: ==========【请修改这里的配置！】 ==========
set "PY_VER=310"                :: python版本 3.9写39，3.10写310，3.11写311
set "OUT_DIR=./linux_offline"   :: 下载输出文件夹
set "REQ_FILE=requirements.txt" :: 依赖清单
set "PLATFORM=manylinux2014_x86_64"
:: ========================================
if not exist "%REQ_FILE%" (
    echo 错误：未找到 %REQ_FILE% ,请把脚本放到requirements.txt同一目录!
    pause
    exit /b 1
)
echo.
echo 目标Python版本: %PY_VER%
echo 输出目录: %OUT_DIR%
echo 依赖文件: %REQ_FILE%
echo.
:: 创建输出文件夹
if not exist "%OUT_DIR%" mkdir "%OUT_DIR%"
:: 执行pip download跨平台下载
pip download ^
-r "%REQ_FILE%" ^
-d "%OUT_DIR%" ^
--only-binary=:all: ^
--platform %PLATFORM% ^
--python-version %PY_VER% ^
--implementation cp ^
-i https://pypi.tuna.tsinghua.edu.cn/simple
echo.
echo ==============================================
echo 下载完成！包输出目录: %OUT_DIR%
echo 将 %OUT_DIR%文件夹 + %REQ_FILE% 拷贝到Linux离线机器
echo Linux离线安装命令：
echo pip install --no-index --find-links=./linux_offline -r requirements.txt
echo ==============================================
pause

✅脚本使用步骤：

将脚本和requirements.txt放在同一个文件夹
修改脚本顶部配置区，设置目标Linux机器Python版本
CMD执行或者直接双击bat运行
将生成的linux_offline文件夹+requirements.txt拷贝到内网Linux服务器，复制脚本输出的安装命令直接运行

✅安装完成验证

复制代码

pip list

核对清单内所有包版本是否全部成功安装。

💡高频踩坑避坑总结

❗Python版本必须完全一致，3.10下载的whl不能给3.9用
❗跨平台必须指定--platform，Windows本机下载不能直接拿给Linux
❗必须加--only‑binary=:all:，否则下载源码包离线编译报错
❗离线安装务必带上--no-index，否则pip会偷偷联网，隔离环境直接超时报错
❗不要手动一个个装whl，子依赖不会自动处理，优先用--find-links批量安装
部分小众包没有对应平台whl二进制包，这种离线场景下只能提前准备编译环境