【# Python 离线安装：把 pip 源设为本地目录】
适用场景：生产机无外网、内网白名单、离线容器构建、CI/CD 离线 Runner 等。
一句话方案（全局生效）
# 让 pip 不再访问外网索引（如 PyPI）
pip config set global.no-index true# 指向你准备好的本地离线包目录（wheel 仓库）
pip config set global.find-links /opt/wheel
之后执行
pip install <pkg>或pip install -r requirements.txt将只从/opt/wheel搜索并安装。
等价的环境变量方案（临时/可脚本化）
export PIP_NO_INDEX=1
export PIP_FIND_LINKS=/opt/wheel# 示例
pip install flask==3.0.3
配置文件方案（持久化、多平台路径）
你也可以通过写入 pip 配置文件来持久化。
- Linux/macOS（全局）：
/etc/pip.conf - Linux/macOS（当前用户）：
~/.config/pip/pip.conf（老版本可能是~/.pip/pip.conf） - Windows（当前用户）：
%APPDATA%\pip\pip.ini - Windows（全局）：
C:\ProgramData\pip\pip.ini
示例内容：
[global]
no-index = true
find-links = /opt/wheel
也可用 自定义配置文件：设置
PIP_CONFIG_FILE=/path/to/pip.conf让某个脚本/容器只读它。
准备离线目录（/opt/wheel）
离线目录就是一个普通文件夹，里面放 .whl 与可选的 .tar.gz 源包。推荐预先下载依赖生成 wheelhouse：
1) 快速下载一批依赖
# 在一台可联网、与目标环境同架构/同Python大版本的机器上
tmp=/tmp/wheelhouse && mkdir -p "$tmp"# 从 requirements.txt 批量下载
pip download -r requirements.txt -d "$tmp"# 也可按需下载
pip download "psycopg2-binary==2.9.9" -d "$tmp"# 拷贝至目标机
rsync -av "$tmp/" user@target:/opt/wheel/
尽量下载 manylinux/abi3 的
.whl，避免离线时本地编译。
2) 将源码包转为 wheel（更保险）
若遇到只有源码包 .tar.gz：
# 为了可重用，把源码包都预编译成 wheel
python -m pip wheel --no-index --find-links "$tmp" -r requirements.txt -w "$tmp"
在虚拟环境中使用（推荐）
python -m venv .venv
source .venv/bin/activate# 方式A：环境变量
export PIP_NO_INDEX=1
export PIP_FIND_LINKS=/opt/wheel# 方式B：写入当前项目的 pip.conf（对新 pip 与 virtualenv 生效）
mkdir -p ./.pip
cat > ./.pip/pip.conf <<'INI'
[global]
no-index = true
find-links = /opt/wheel
INI
export PIP_CONFIG_FILE=$PWD/.pip/pip.confpip install -r requirements.txt
requirements.txt 中内嵌离线指令（自包含）
在 requirements.txt 顶部加入（注意只在离线使用）：
--no-index
--find-links=/opt/wheelFlask==3.0.3
psycopg2-binary==2.9.9
这样你只需：
pip install -r requirements.txt
常见问题 & 排错
1) 明明有包却提示找不到
-
确认 包名/版本 与文件名一致（如
flask-3.0.3-py3-none-any.whl）。 -
检查
find-links是否包含 正确目录；可配置多个：find-links = /opt/wheel/mnt/another-wheel -
确认 Python 大版本/平台标签兼容（如 cp312、manylinux、win_amd64）。
2) 离线时仍然试图联网
- 是否某处留下了
--index-url或--extra-index-url？和--no-index冲突。 - Dockerfile/脚本里是否覆盖了
PIP_NO_INDEX/PIP_CONFIG_FILE？
3) 私有包如何组织？
-
简单做法：把私有包 wheel 也丢进
/opt/wheel。 -
进阶做法：在内网起一个简单 HTTP 目录服务（如
python -m http.server 8000指向 wheel 目录），然后：pip install --no-index --find-links http://intranet:8000 <pkg>注意：这是 find-links 静态目录，不是 PyPI 协议服务器。
实战模板
Dockerfile 片段（离线构建）：
COPY wheel/ /opt/wheel/
ENV PIP_NO_INDEX=1 \PIP_FIND_LINKS=/opt/wheelRUN python -m pip install --upgrade pip \&& pip install -r /app/requirements.txt
系统级永久配置（Linux）：
sudo install -d -m 755 /etc/pip.conf.d
sudo tee /etc/pip.conf >/dev/null <<'INI'
[global]
no-index = true
find-links = /opt/wheel
INI
小结
- 核心：
--no-index+--find-links=<本地目录或内网URL>。 - 三种持久化：
pip config、配置文件、环境变量。 - 提前准备 wheel：
pip download+ 可选pip wheel，尽量避免离线编译。