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
    1. Instant Client Basic
    2. 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
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


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!

. ~/.bash_profile
mkdir /Users/username_here/virtualenvs
cd /Users/username_here/virtualenvs
pip install virtualenv # If you haven't already
virtualenv --python=python3.6 venv # It's 2017, time for Python 3
. venv/bin/activate
pip install cx_Oracle


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

>>> import cx_Oracle
>>> cx_Oracle.version
>>> conn = cx_Oracle.connect('pythonhol/welcome@')
>>> conn.version
>>> conn.close()


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

10 thoughts on “Installing cx_Oracle on a Mac: 2017 Edition”

  1. Hi ,

    I have followed your blog step by step and try to connect the database. Though it give me TNS error and i am unable to connect.
    cx_Oracle.DatabaseError: ORA-12514: TNS:listener does not currently know of service requested in connect descriptor

    I will appreciate your help/suggestion.


    1. So good news. That error is not an error related to installing/using the library! Congrats! That error is most likely related to something in your connection string. I would work with your Database team (or if you are the database team) to figure out the right format for connection strings. I am not the best when it comes to specifics but I would say this is a good starting point:

      Also figure out the DB version you are connecting to as that could change!

  2. Followed the steps and I am seeing an error:

    >>> import cx_Oracle
    Traceback (most recent call last):
    File “”, line 1, in
    ImportError: dlopen(/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/, 2): Symbol not found: _OCIAQDeq
    Referenced from: /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/
    Expected in: dynamic lookup

    ??? Any ideas

  3. Hi Joel, I’m having some trouble with the vim ~/.bash_profile command, once I type that it opens up a new thing where I typed the export commands (, but I don’t think I’m updating the bash_profile properly, I’ve tried using the esc key and “:w” and enter key, that appeared to take me out of edit mode, but when I tried to run “.~/.bash_profile” I got an error (

    Is there something I’m doing wrong?

    Thank you

    1. Kri, sorry for the delay in response, hopefully you fixed it. but you need a space between the . and the ~/.bash_profile.

      Opening another terminal should have fixed it, and i’m sure by now you probably also restarted your system. Basically the . ~/.bash_profile is used to reload your terminal with system variables. No need to keep doing it 🙂

      Hope all is working 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.