Installing cx_Oracle on a Mac: 2017 Edition

Hello internet friends! I am back with a much needed follow up on my old cx_Oracle install guide on Mac from 2013. Thanks for everyone for the feedback over the years, and glad that I was able to help so many folks. After many comments (and a new MacBook), I have decided to polish up my guide. Luckily, it appears cx_Oracle is now on PyPI (no more compiling it yourself!) and the process is much much easier! Let’s get started!

What’s new from last time?

No more need for sudo access; leverage user space properly.

• sudo/root should generally be reserved for system level operations or at least operations you are familiar with. Never trust random sudo commands you find, they can seriously mess up your system.
• This was one of my biggest complaints about the old article

No more compiling cx_Oracle from SourceForge.

• It is now in PyPI…thank you sweet developers!

It works in a virtualenv

• No longer do you need to setup cx_Oracle at the system level! You can now use standard virtualenvs. Nothing is stopping you from installing at the system though!

It works in Python 3.

• Time to move to Python 3 everyone. This guide is written for Python 3, although the steps for Python 2 shouldn’t be too different.

Less steps overall

• Before there was a bunch of unzip library files and also symlinking random files. I don’t have time to check but it looks like the process has been improved significantly.

Necessary Downloads:

1. Oracle 12.1 Instant Client 64-bit Libraries

• Instant Client Basic
• Instant Client SDK

2. virtualenv — Optional but avoids polluting system pip environment by creating virtual python environments!

Next Steps:
Assuming you downloaded all the above files (except virtualenv), and they are found in your Downloads directory, run the following commands:

mkdir /Users/<username_here>/oracle
mv /Users/<username_here>/Downloads/instantclient-* /Users/<username_here>/oracle
cd /Users/<username_here>/oracle
unzip instantclient-basic-macos.x64-12.1.0.2.0.zip
unzip instantclient-sdk-macos.x64-12.1.0.2.0.zip
cd instantclient_12_1/
ln -s libclntsh.dylib.12.1 libclntsh.dylib
vim ~/.bash_profile

Run the following lines (you should add these lines to your .bash_profile too):

export ORACLE_HOME=/Users/<username_here>/oracle/instantclient_12_1
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME

Once you enter all the info, you should re-source your bash_profile. Once your changes are in your .bash_profile, the instant client should be setup! Validate all your settings are correct by doing:

. ~/.bash_profile
echo $ORACLE_HOME # should be /Users/username_here/oracle/instantclient_12_1 if you followed this guide
echo $LD_LIBRARY_PATH # same as above
which python # usually /usr/bin/python or your virtualenv

If all of the above is set, then you are ready to proceed with the cx_Oracle install!

If all went according to plan, it should have successfully installed! (if not post in the comments and I can help!) To test simply:

python
>>> import cx_Oracle
>>> cx_Oracle.version
'5.3'
>>> conn = cx_Oracle.connect('pythonhol/welcome@127.0.0.1/orcl')
>>> conn.version
'11.2.0.1.0'
>>> conn.close()

Hopefully this new and improved guide gets you folks up and running faster! As always, I look for your feedback below!

Originally published at https://joelvasallo.com on June 4, 2017.