Ubuntu 24.04 下 pip 安装华为云 Python SDK 触发 PEP 668 报错？两种解法实测

一、背景

最近在 Ubuntu 24.04 的机器上写自动化脚本，需要调用华为云 API，第一步就是装 Python SDK。按习惯敲下 pip install huaweicloudsdkcore，结果直接报错退出。查了一圈发现这是从 Python 3.11 起 Debian 系发行版的默认行为（PEP 668），不是华为云 SDK 的问题。本文把报错复现、两种解法的实测结果以及一个连带踩到的坑记录下来。

二、实测环境

• 操作系统：Ubuntu 24.04.5 LTS
• Python：3.12.3（系统自带）
• pip：24.0（/usr/lib/python3/dist-packages/pip，系统 pip）

三、复现报错

执行：

pip install huaweicloudsdkcore

返回：

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

关键点：从 Python 3.11 起，Debian/Ubuntu 给系统 Python 打上了“外部管理”标记，pip 默认拒绝往系统 site-packages 里装包，怕和 apt 管理的包冲突。华为云官方未提供 apt 包，所以这条路走不通。实测连 pip install --user 也会被同一机制拦截。

四、解法一：--break-system-packages（能用，但不推荐）

pip install --break-system-packages huaweicloudsdkcore huaweicloudsdkecs huaweicloudsdkvpc huaweicloudsdkeip

实测可以装上。但这个 flag 的名字已经把风险写明了：它会绕过 PEP 668 保护，往系统环境里写包。哪天 apt upgrade 动了系统 Python 依赖，就可能把环境搞坏。个人实验机图省事可以用，生产环境别这么干。

五、解法二：venv 虚拟环境（推荐）

实测全程无报错：

python3 -m venv /tmp/hwc-test-venv
/tmp/hwc-test-venv/bin/pip install huaweicloudsdkcore

Successfully installed certifi-2026.10.19 charset_normalizer-3.5.2
defusedxml-0.7.1 dnspython-2.9.0 huaweicloudsdkcore-3.1.219
idna-3.20 pyasn1-0.6.3 pymongo-4.18.2 pyyaml-6.0.3
requests-2.34.2 requests-toolbelt-1.0.0 simplejson-4.2.0
six-1.17.0 urllib3-2.8.0

虚拟环境里的 pip 不受 PEP 668 限制，不需要任何 flag，一次成功。装好的是 huaweicloudsdkcore 3.1.219。注意：全新安装的 Ubuntu 可能需要先 sudo apt install python3-venv，否则 python3 -m venv 会因缺 ensurepip 报错。

六、连带踩到的坑：core 包不含业务 SDK

只装 huaweicloudsdkcore 的情况下跑：

from huaweicloudsdkecs.v2 import EcsClient

实测报错：

ModuleNotFoundError: No module named 'huaweicloudsdkecs'

huaweicloudsdkcore 只是认证、鉴权、HTTP 封装等基础能力，ECS、VPC、EIP 这些业务 SDK 是独立包，必须单独装：

/tmp/hwc-test-venv/bin/pip install huaweicloudsdkecs huaweicloudsdkvpc huaweicloudsdkeip

Successfully installed huaweicloudsdkecs-3.1.219
huaweicloudsdkeip-3.1.219 huaweicloudsdkvpc-3.1.219

实测发现：单独装 huaweicloudsdkecs 会自动把 huaweicloudsdkcore 3.1.219 作为依赖带上，所以实际使用时直接装需要的业务包即可，不用先装 core。

七、验证 SDK 真的可用

用占位符凭证构造客户端（不要把真实 AK/SK 写进代码或文章）：

from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkecs.v2.region.ecs_region import EcsRegion
from huaweicloudsdkecs.v2 import EcsClient

credentials = BasicCredentials('YOUR_AK', 'YOUR_SK', 'YOUR_PROJECT_ID')
client = EcsClient.new_builder() \
    .with_credentials(credentials) \
    .with_region(EcsRegion.value_of('cn-north-4')) \
    .build()
print('client built OK')

实测输出 client built OK（type(client).__name__ == 'EcsClient'），说明 SDK 在 venv 里工作正常。注意这一步只是在本地构造客户端对象，没有发起真实 API 调用；with_region 必须传 EcsRegion.value_of(...) 返回的 Region 对象，传裸字符串会报 AttributeError。AK/SK 请从控制台“我的凭证”获取，project ID 是 32 位字符串，注意别填成区域名（如 cn-north-4 是区域名，不是 project ID）。

八、总结

• Ubuntu 24.04 + Python 3.12 下 pip install 报 externally-managed-environment 是 PEP 668 的预期行为（从 Python 3.11 起），不是 SDK 的 bug；
• 推荐用 python3 -m venv 建虚拟环境再装，不需要 --break-system-packages；
• huaweicloudsdkcore 只是底座，业务包（ecs/vpc/eip/ims……）要按需单独装，直接装业务包会自动带上 core；
• 凭证用占位符，project ID 别和区域名搞混。