必须用pip download加--platform、--python-version等参数精准下载并锁定版本,否则pypiserver离线安装会因平台标签不匹配或依赖漏装而失败。

直接用 pypiserver 搭建最省事,但必须避开平台标签不匹配、依赖漏下载、服务未绑定内网地址这三类高频故障。
为什么不能只 pip install *.whl 放进目录就完事
这是企业离线部署里最常踩的坑:把一堆 .whl 文件丢进 packages/ 目录,启动 pypiserver 后发现 pip install requests 报错 ERROR: Package 'urllib3' requires a different Python。根本原因是:pip install *.whl 不校验平台标签(如 cp311-manylinux_2_17_x86_64),也不递归拉取间接依赖(requests 依赖 urllib3 和 certifi,但你只下了 requests)。最终结果是“看似能装,运行时报 ImportError”。
- 必须用
pip download --platform --python-version --abi --only-binary=:all:精准下载,基准以目标机输出为准:python -c "import pip._vendor.packaging.tags; print(list(pip._vendor.packaging.tags.sys_tags())[0])" -
requirements.txt中所有包必须锁定版本(numpy==1.24.3),禁用>=或~;删掉-e .、git+、file://这类离线不可用的行 - 检查 wheelhouse 是否干净:
ls ./packages | grep -v 'cp311.*manylinux_2_17_x86_64'—— 有输出就得清掉
pypiserver 启动时为什么本地能用,内网其他机器连不上
默认 pypi-server run ./packages 只监听 127.0.0.1,相当于“只给自己用”。内网其他机器访问 http://your-server-ip:8080/simple/ 会直接超时。
将测试、lint、构建和文档流程编码为命名的Python会话,以便人类和代理每次运行相同的workflow。
- 启动命令必须加
--host 0.0.0.0:pypi-server --host 0.0.0.0 --port 8080 ./packages - 确认防火墙放行端口:
sudo ufw allow 8080(Ubuntu)或sudo firewall-cmd --add-port=8080/tcp --permanent(CentOS) - 验证方式不是打开浏览器看首页,而是从另一台内网机器执行:
curl -I http://your-server-ip:8080/simple/requests/,返回200 OK才算通
如何让 pip install 自动走私有源,而不是每次敲 -i
靠临时加 -i http://xxx/simple/ 容易漏、难维护。全局配置才是生产环境该用的方式。
- 在每台内网机器上执行:
pip config set global.index-url http://your-server-ip:8080/simple/ - 配置文件位置因系统而异:
~/.pip/pip.conf(Linux/macOS)或%APPDATA%\pip\pip.ini(Windows),手动编辑也行,但优先走pip config命令 - 验证是否生效:
pip config list应看到global.index-url='http://your-server-ip:8080/simple/';再跑pip install requests -v,日志里会显示从你的地址下载 - 注意:如果之前设过其他源(如清华源),这条命令会覆盖它;如有需要保留备份,先
pip config list -v查路径再手动备份
真正卡住人的从来不是“怎么启动服务”,而是 wheel 标签和目标环境对不上、requirements.txt 里混了源码包、或者忘了开防火墙——这些点不提前扫一遍,后面查半天网络或权限,实际问题却在包本身。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










