在CMD与PyCharm中安装cx-Oracle遇wheel构建失败问题求助

1. 安装Oracle客户端依赖 #

cx-Oracle必须依赖Oracle Instant Client才能完成编译，步骤如下：

• 下载与你的Python版本、Oracle服务器版本匹配的Oracle Instant Client Basic或Basic Light包
• 解压后，将解压路径添加到系统PATH环境变量（Windows用户可通过「此电脑→属性→高级系统设置→环境变量」操作），或设置ORACLE_HOME环境变量指向解压目录

2. 更新pip、setuptools和wheel工具 #

旧版本的构建工具可能引发失败，执行命令更新：

pip install --upgrade pip setuptools wheel

3. 直接安装预编译二进制包 #

跳过本地构建，直接用预编译好的wheel包安装：

• 执行以下命令强制使用预编译包：

pip install cx-Oracle --only-binary :all:

• 若上述命令失效，可手动下载对应系统和Python版本的cx-Oracle wheel包，再执行本地安装：

pip install 本地wheel包的完整路径

4. 校验Python与客户端架构匹配 #

确保Python的位数（32位/64位）和Oracle Instant Client完全一致：

• 在CMD中执行命令查看Python架构：

python -c "import sys; print(sys.maxsize > 2**32)"

返回True为64位，False为32位，对应匹配同位数的客户端包

5. 安装Windows编译工具（仅Windows环境） #

Windows下构建wheel需要Visual C++编译组件，缺失会导致编译失败：

• 安装微软Visual C++ Build Tools，安装时勾选「C++ build tools」核心组件
• 安装完成后重启CMD或PyCharm，再尝试安装cx-Oracle

报错信息：Building wheel for cx-Oracle (pyproject.toml) did not run successfully. exit code: 1

内容的提问来源于stack exchange，提问作者Furyan Abuji