cx_Oracle安装失败的根本原因是其依赖Oracle Instant Client动态库，而pip仅安装Python层代码，不自动配置客户端；必须确保Python、Instant Client和操作系统三者位数一致，并正确设置PATH（Windows）或LD_LIBRARY_PATH/DYLD_LIBRARY_PATH（Linux/macOS）环境变量。
cx_Oracle 是 Python 连接 Oracle 的主流驱动，但它的安装不是 pip install cx_Oracle 一行命令就能完事的——它依赖 Oracle 客户端库，缺了就直接报 ImportError: DLL load failed 或 libclntsh.so: cannot open shared object file。
为什么 pip install cx_Oracle 经常失败？
因为 cx_Oracle 不是纯 Python 包，它需要底层 Oracle 客户端（Instant Client）提供 oci.dll（Windows）或 libclntsh.so（Linux/macOS）。pip 安装只负责 Python 层，不自动下载/配置客户端。
- Windows 上常见错误：
ImportError: DLL load failed: 找不到指定的模块 - Linux 上常见错误：
cx_Oracle.DatabaseError: DPI-1047: Cannot locate a 64-bit Oracle Client library - macOS 上常见错误：
OSError: dlopen(.../cx_Oracle.cpython-*.so, 0x0002): tried: ... (no suitable image found)
必须匹配的三个位数：Python、Instant Client、操作系统
三者必须同为 64 位（或全为 32 位），混搭必报错。现在几乎全是 64 位环境，所以：
- 确认 Python 位数：
python -c "import platform; print(platform.architecture())"→ 输出('64bit', 'WindowsPE')才对 - 下载对应 Instant Client：Oracle 官网下载页，选
Basic（不是 SDK）和你的系统版本（如instantclient-basic-windows.x64-21.12.0.0.0.zip） - 解压后目录不能含空格或中文，例如
C:\oracle\instantclient_21_12是安全路径；C:\Program Files\...很可能触发权限或路径解析问题
Windows 下最简可行配置
不用改系统环境变量，也不用复制 .dll 到 site-packages（那是旧版做法，容易污染）：
立即学习“Python免费学习笔记（深入）”；
- 解压 Instant Client 到固定路径，比如
C:\oracle\instantclient_21_12 - 在 Python 脚本开头加两行（**必须在 import cx_Oracle 之前**）：
import os os.environ["PATH"] = r"C:\oracle\instantclient_21_12" + os.pathsep + os.environ["PATH"]
- 再执行
import cx_Oracle，就能正常加载 - 如果要用中文字段，加一句：
os.environ["NLS_LANG"] = "AMERICAN_AMERICA.AL32UTF8"（推荐 UTF8，避免乱码）
Linux/macOS 必须设 LD_LIBRARY_PATH / DYLD_LIBRARY_PATH
Instant Client 解压后，需显式告知系统动态库位置：
- Linux：
export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_12:$LD_LIBRARY_PATH
（写进~/.bashrc或启动脚本） - macOS（M1/M2/M3）：
export DYLD_LIBRARY_PATH=/opt/oracle/instantclient_21_12:$DYLD_LIBRARY_PATH
（注意不是LD_LIBRARY_PATH） - 验证是否生效：
ldd python -c "import cx_Oracle"或直接运行python -c "import cx_Oracle; print(cx_Oracle.version)" - 符号链接不是可选项：
cd /opt/oracle/instantclient_21_12 && ln -s libclntsh.dylib.21 libclntsh.dylib（macOS）或ln -s libclntsh.so.21 libclntsh.so（Linux）
真正卡住人的从来不是代码，而是 Instant Client 的路径没被 runtime 看见，或者位数/编码/符号链接三者中任意一个没对齐。
