Open WebUI 离线部署时，依赖包下载失败通常发生在 pip 尝试访问 PyPI 但网络不可达或代理受限的阶段。处理这一问题的核心是两条路径：改用可用的内网 pip 镜像，或在一台联网机器上提前准备好 wheel 包并搬运到目标环境。二者并不互斥，建议按实际网络条件组合使用。

依赖下载失败要先分清是网络不可达、DNS 解析失败还是镜像源不支持当前 Python 版本。可先尝试更换 pip 镜像源；若目标机器完全离线，则需要在联网机器上用 pip download 拉取全套依赖，连同 Open WebUI 安装包一起拷贝到离线环境，再用本地目录安装。任何镜像地址和版本约束都要结合目标环境的 Python 版本和 Open WebUI 版本确认。

先判断失败类型

在动手换源之前，先观察 pip 报错。常见情况有三种：

• 连接超时或连接被拒绝：多为网络策略阻断，换用内网镜像通常有效。
• 404 或文件未找到：镜像源地址写错，或镜像未同步对应 Python 版本的 wheel。
• 解析错误或证书校验失败：可能是 pip 版本过旧，或镜像使用了自签名证书，需要更新 pip 或配置 trusted-host。

先执行一次最简单的安装命令，加上超时和重试参数，能看到更明确的错误位置：

pip install `--timeout` 60 `--retries` 3 open-webui

如果仍然失败，再考虑改镜像。改镜像有两种方式：临时指定和写入配置文件。临时指定适合验证连通性：

pip install -i http://mirrors.internal.example.com/pypi/simple/ open-webui

如果该镜像可用，再持久化配置。Linux 下 pip 配置文件通常在 ~/.config/pip/pip.conf 或 /etc/pip.conf，Windows 下在 %APPDATA%\pip\pip.ini。写入内容时，注意镜像地址必须带 /simple 路径，否则 pip 无法识别索引目录。

使用本地 wheel 缓存完成离线安装

如果目标机器没有外网，也没有内网镜像，就需要在联网机器上把依赖全部拉下来。关键是使用 pip download 而非 pip install，因为 download 不会执行安装，只把 wheel 包保存到指定目录。

pip download open-webui -d ./openwebui_wheels

这样会下载 Open WebUI 及其所有依赖，但默认只下载当前平台和 Python 版本对应的 wheel。如果目标机器与下载机器操作系统或 Python 版本不同，需要指定 `--platform`、`--python-version`、`--implementation` 和 `--abi` 参数，例如：

pip download open-webui -d ./openwebui_wheels \n    `--platform` manylinux2014_x86_64 \n    `--python-version` 311 \n    `--implementation` cp \n    `--abi` cp311 \n    `--only-binary`=:all:

这里的参数严格对应当前 pip 的 wheel 命名规则，需要根据目标环境的实际值调整。复制整个 openwebui_wheels 目录到离线机器后，直接用它作为安装源：

pip install `--no-index` `--find-links` ./openwebui_wheels open-webui

`--no-index` 告诉 pip 不要访问 PyPI，`--find-links` 指定本地目录。若下载时包含了所有依赖，这一步应该能完成安装。如果某个依赖缺失，pip 会明确指出缺哪个包，回到联网机器补下即可。

避免常见坑点

• 不能用 pip install `--download` 旧语法，新版本 pip 已经移除该选项，使用 pip download 命令。
• 如果 Open WebUI 依赖中包含源码包（sdist），在离线环境本地安装时可能需要编译，导致缺少编译器而失败。尽量避免，下载时优先 `--only-binary`=:all:。
• Open WebUI 的依赖较多，包括 tokenizers、pydantic、sentence-transformers 等，下载目录会很大。建议整理一个 requirements.txt 并固定版本，方便后续复现。
• 换镜像源时，不要用 http 镜像且不校验证书的配置直接推广到生产环境，先确认镜像来源可信。

验证安装结果

离线安装完成后，启动 Open WebUI 前建议先验证依赖是否完整：

pip check open-webui

该命令会报告已安装包的依赖冲突或缺失。再启动服务并观察日志，确认没有导入错误。若服务启动后页面能正常加载，说明依赖下载和处理已经闭环。

处理流程可以归纳为：先确认网络和 pip 版本，再尝试镜像源；若离线，用联网机器做 wheel 下载，搬运到目标机器后用本地目录安装。每一步都要根据当前环境的 Python 版本、操作系统架构和 pip 版本做适配，不要照搬命令。