我之前也踩过这个坑，给你梳理几个最容易出错的点，按顺序排查应该能解决问题：

1. 确保Oracle客户端与Python位数完全匹配 #

这是最常见的问题！如果你的Python是64位，必须安装64位的Oracle Instant Client（不用装完整客户端，Instant Client足够），反之32位Python对应32位客户端。

验证Python位数的方法：

import sys
print(sys.maxsize > 2**32)  # 返回True是64位，False是32位

2. 环境变量设置必须生效且优先级正确 #

Windows系统： #

• 把Oracle Instant Client的根目录（比如C:\instantclient_19_12）添加到PATH环境变量的最顶部，避免系统优先找到其他旧版本的Oracle库。
• 重要：设置完环境变量后，必须关闭所有正在运行的终端、IDE（比如VS Code、PyCharm），重新打开再运行代码——环境变量不会实时生效。

Linux/macOS系统： #

• 临时生效：在终端中执行以下命令（替换为你的Instant Client路径）：

  # Linux
  export LD_LIBRARY_PATH=/path/to/instantclient:$LD_LIBRARY_PATH
  # macOS
  export DYLD_LIBRARY_PATH=/path/to/instantclient:$DYLD_LIBRARY_PATH
  

  然后在同一个终端运行Python脚本。
• 永久生效：把上述命令添加到~/.bashrc（Bash）或~/.zshrc（Zsh）文件中，保存后执行source ~/.bashrc使设置生效。

3. 检查cx_Oracle与Oracle客户端的版本兼容性 #

cx_Oracle的新版本对Oracle客户端版本有要求：

• cx_Oracle 8.x及以上需要Oracle Client 12.2+
• cx_Oracle 7.x支持Oracle Client 11.2+

你可以用以下命令查看当前cx_Oracle版本：

pip show cx_Oracle

如果版本不兼容，要么升级Oracle客户端，要么降级cx_Oracle到匹配的版本。

4. 避免多Oracle环境冲突 #

如果你的机器上装了多个Oracle相关软件（比如PL/SQL Developer、Oracle数据库本地客户端），它们的库可能会和Instant Client冲突。解决方法：

• 把Instant Client的PATH（Windows）或LD_LIBRARY_PATH（Linux/macOS）放在所有其他Oracle相关路径的前面。
• 暂时卸载其他不必要的Oracle软件，排查是否是冲突导致。

5. 验证Oracle客户端本身是否正常工作 #

在终端中用sqlplus测试连接：

sqlplus your_username/your_password@db_host:db_port/service_name

如果sqlplus能成功连接，说明客户端配置没问题，问题出在Python环境没有正确读取到环境变量；如果sqlplus也报错，那先解决Oracle客户端的安装配置问题。

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