Home > Coding, Inspired, Intuition > Installing cx_Oracle on Windows

Installing cx_Oracle on Windows

Almost 2 months ago, I started on a project that required the use of Python and access to an Oracle database. It took me multiple days in a row to finally get it up and running so that I could actually make progress on the project, but once I did, I thought nothing of finally getting it to work. However, I was recently approached by another person at work who had to use the cx_Oracle package to access an Oracle DB through Python, and realized the value of actually putting together a post about the steps required.

First off, it is really easy to get it running on Linux. I mean super easy to get Python and cx_Oracle up and running. Secondly, I have an XP machine at work, so no guarantees that this will work with all other Windows Operating Systems until I get to test it on one (not possible till about September at the earliest, I’ll put a todo item in my calendar to try to remember to do it).

Alright, down to the nitty-gritty of it. You first need to install a recent, if not the latest, version of Python, if you don’t already have it of course. When I was installing it on my work computer, that was Python 2.6.5. Now that would be Python 2.7, but since Python is intentionally backwards compatible, it SHOULDN’T matter. For installing Python, be sure to follow one of the many Python install guides available on the web, but the quick run-down of the install process is:

  1. Install Python.
  2. Edit your environment variables to add the Python directory to your PATH variable and create a PYTHON variable. I will cover editing/creating Environment Variables with the later part of this guide because you will have to do it again for cx_Oracle.
  3. Code in Python (you can use an IDE like Eclipse, or a regular text editor like Notepad++).

Next, run the cx_Oracle .msi installer for your particular Windows install. Now that was the easy part.

Next up is the part that most people seem to miss, having an Oracle client on your local machine. Oracle suggests the use of the Oracle Instant Client (updated link thanks to Tim in the comments), and that’s what I used this time. Oracle’s instructions seem to have improved since I first installed the Oracle Instant Client, but that doesn’t mean they are easy to follow.

  1. Go download, and unzip, the Oracle Instant Client from here.
  2. Put it in a place on the C:\ drive that is easy to find/access later (it’s a drag and drop procedure for getting the files there, no installer). My suggestion is to create a directory called Oracle, and place the instantclient directory in there. This way, my path to the Instant Client directory reads “C:\Oracle\instantclient”.
  3. Add this guy to your PATH Environment Variable. You can get to the Environment Variables by right clicking My Computer, select Properties, go to the Advanced tab, click the button that says “Environment Variables”, and now we’re here. From the Python install, your PATH variable (in the user variables section, not the system variables) should already exist from you creating it as “C:\Pythonxx”. Now, add that directory location from step 2 so that the PATH variable reads similarly to mine, which is “C:\Oracle\instantclient;C:\Python26″.
  4. Now you are going to need a tnsnames.ora file. For those of you that don’t know what that is, read here. The company I work for fortunately provided me with one, so I didn’t have to make it from scratch, but basically they contain your connection strings to the different databases you are going to be accessing. I saved mine to “C:\Oracle\network\admin” just for easy memory (and because that’s where someone else’s was when I asked). I hope you didn’t close the Environment Variables screen, you’re going to need it again.
  5. Lastly, you need to add the TNS_ADMIN variable with step 4’s path in it.

You have now installed cx_Oracle successfully. To really test it, you can open up a Python command prompt and run the following lines of code to test it (case sensitive).

  • import cx_Oracle
  • db_conn = cx_Oracle.connect(“user/pass@tnsname.world”)

If either of those steps went wrong, double check the steps. If you still don’t know, comment on the post, or email me (my email is lying around somewhere on this site), and I’ll do my best to help you. There are also many forums and forum threads scattered around that have tried to explain these points as well, but I found them to be inadequate.

Lastly, Google is your friend for finding out about the different functions available in cx_Oracle, and the documentation isn’t terrible for this either.

Be Sociable, Share!
  1. Arun
    October 31st, 2012 at 01:49 | #1

    Very helpful… thank you

  2. Tim Allbee
    January 27th, 2013 at 23:44 | #2

    Found this article very helpful. The Oracle Instant Client section is important and that was what I was missing with my cx_Oracle installation. The Oracle Instant Client link, as of Jan 2013, is http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html Of course, simple search would take you there.

    Another small detail is that when you are importing “cx_Oracle” to test make sure that you have it as you see it as that module text is case SENSITIVE.


  3. January 28th, 2013 at 00:05 | #3

    @Tim Allbee

    Thanks Tim for the updated info! I’ve added the new link to the body of the post and noted that those lines are case sensitive.

  4. tSant
    August 27th, 2013 at 10:35 | #4


    I know this is an old post, but since I am having this issue with cx_oracle now and this is the most complete post on the matter, I will try my luck and as anyway in the hopes that someone will kindly reply.

    My problem is I need to put a python script that queries and updates data on an oracle database on a Windows Server machine that currently has an Oracle Server installed. cx_Oracle has been properly installed but then I keep getting this error:

    >>> import cx_Oracle as ora
    >>> conn = ora.connect(‘xxxxxxx/xxxxxx@xxxxxx/xxxxxxx’)

    Traceback (most recent call last):
    File “”, line 1, in
    conn = ora.connect(‘tib_241_corporate_test/orga123@riosun12/opscgold’)
    InterfaceError: Unable to acquire Oracle environment handle

    The oracle instance I am trying to access is not the same one hosted on this Windows Server machine, but, since it has an Oracle Server installed which I would think has all the libraries (dlls) necessary to access other oracle databases (given that I have other tools that require oracle libs…), why does this not work?

    Is oracle instant client strictly necessary even if an Oracle Server installation is available and correctly map at the machine’s PATH, LD_LIBRARY_PATH and ORACLE_HOME?

    Thank you,

  5. September 22nd, 2013 at 13:20 | #5

    Sorry for the super late reply @tSant, I don’t get on my blog very often these days.

    Check out http://stackoverflow.com/questions/13589683/interfaceerror-unable-to-acquire-oracle-environment-handle-oracle-home-is-corr or this message thread http://osdir.com/ml/python.db.cx-oracle/2006-01/msg00004.html

    Otherwise, gotta make sure your tnsnames.ora file is correctly pointed at the server. Shouldn’t matter where the oracle server is as long as your tnsnames file is pointed at it properly.

  6. Hussein
    October 7th, 2013 at 10:20 | #6

    I stumbled upon this website while trying to do the same and while the instructions were great, they didn’t help. For the sake of anyone else trying to do the same, I fiddled around with Process Monitor and found it was trying to load MSVCR71.dll, which the 10g Instant Client didn’t have in the directory. Copying it from elsewhere on my system into that directory fixed the issue for me.

    • October 7th, 2013 at 10:48 | #7

      Nice find! I’ve admittedly not needed to use the instant client (or even Windows as a development environment) in over 2 years, so can’t verify myself, but hopefully that will help someone else in the near future.

  7. Mike
    January 17th, 2014 at 15:18 | #8

    Thanks for the quick guide! Helped me get cx_Oracle going but for some reason I am still having trouble getting the TNS file working.

    Using your example to test: db_conn = cx_Oracle.connect(“user/pass@tnsname.world”)

    I’ve tried various combinations but mostly I get this error:

    cx_Oracle.DatabaseError: ORA-12154: TNS:could not resolve the connect identifier specified

    Wondering if you have any thoughts? Tried putting full path to my TNS names file.


  8. January 18th, 2014 at 15:37 | #9


    It sounds like you have a syntax error in your TNS file because of “could not resolve the connect identifier.” See if that helps.

  9. Hussam
    August 8th, 2016 at 02:24 | #10

    Thank you very much it works well with me.

    Another useful way of login command is:

    cx_Oracle.connect(user=’username’, password=’pass’, dsn=’servername’)

    for some reason this worked and not what was provided in the steps.

  1. April 17th, 2014 at 00:29 | #1