Installing cx_Oracle Driver on El Capitan

Download Oracle instantclient
  1. Navigate to the ‘Oracle Instant Client Downloads’ page.
  2. Download instantclient-basic-macos.x64-12.1.0.2.0.zip and instantclient-sdk-macos.x64-12.1.0.2.0.zip
    • You will need an Oracle account to proceed with the download.
  3. Enter the ‘~/Downloads’ folder in Terminal, and unzip both downloads:
cd ~/Downloads
# Or 'cd <download_directory>'
unzip instantclient-basic-macos.x64-12.1.0.2.0.zip
# Running the below 'unzip' command will automagically 
# place the unzipped contents in 'instantclient_12_1/sdk'
unzip instantclient-sdk-macos.x64-12.1.0.2.0.zip
mv instantclient_12_1 /usr/local/opt/instantclient_12_1
cd /usr/local/opt/instantclient_12_1
ln -s libclntsh.dylib.12.1 libclntsh.dylib
Configure environment variables
# Tell cx_Oracle setup.py where to find instantclient libs
export ORACLE_HOME=/usr/local/opt/instantclient_12_1
# Set -rpath option to tell gcc to look in ORACLE_HOME when linking
export FORCE_RPATH=1

Download and install cx_Oracle
# Install with pip
pip install cx_Oracle
Verify cx_Oracle was correctly installed
python -c "import cx_Oracle"

If this fails then you may see the following exception:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
ImportError: dlopen(/Library/Python/2.7/site-packages/cx_Oracle.so, 2): Library not loaded: @rpath/libclntsh.dylib.12.1
  Referenced from: /Library/Python/2.7/site-packages/cx_Oracle.so
  Reason: image not found

If you are seeing this exception, you either skipped setting ORACLE_HOME and FORCE_RPATH (as described above), or you are using a cached version of the cx_Oracle build when installing. To force pip to re-build the package, run:

pip install --no-cache-dir --allow-external --allow-unverified cx_oracle

Thanks to Christopher Jones for help simplifying the above steps.