cx_Oracle 6 Installation

Overview

Before cx_Oracle can be installed, an installation of Python is needed first. Python 2.7 and Python 3.4 and higher are supported.

The simplest method of installing cx_Oracle is to Install Using Pip. You can also Install Using GitHub. If you run into trouble, check out the section on Troubleshooting. cx_Oracle uses ODPI-C, which means that the ODPI-C installation instructions can be useful to review.

After cx_Oracle has been installed, you must also Install Oracle Client, if that has not been done already. Oracle Client versions 12.2, 12.1 and 11.2 are supported.

Finally, you need an Oracle Database for Python to connect to. Oracle’s standard client-server version interoperability allows cx_Oracle to connect to both older and newer databases. Python can be local or remote to the database.

Upgrading from cx_Oracle 5

If you are upgrading from cx_Oracle 5 note these installation changes:

  • When using Oracle Instant Client, you should not set ORACLE_HOME.
  • On Linux, cx_Oracle 6 no longer uses Instant Client RPMs automatically. You must set LD_LIBRARY_PATH or use ldconfig to locate the Oracle client library.
  • PyPI no longer allows Windows installers or Linux RPMs to be hosted. Use the supplied cx_Oracle Wheels instead.

Install Using Pip

Pip is the generic tool for installing Python packages. If you do not have pip, see the pip installation documentation.

The command to install cx_Oracle 6 using pip on all platforms is:

python -m pip install cx_Oracle --upgrade

This will download and install a pre-compiled binary matching your platform and architecture automatically, if one is available. Pre-compiled binaries are available for Windows and Linux. See PyPI.

If a pre-compiled binary is not available, the source will be downloaded, compiled, and the resulting binary installed. On Linux if cx_Oracle needs to be compiled for the default python package, you will need the python-devel package or equivalent, which provides the Python.h header file.

On macOS make sure you are not using the bundled Python - use Homebrew or Python.org instead.

Install Using GitHub

In order to install using the source on GitHub, use the following commands:

git clone https://github.com/oracle/python-cx_Oracle.git cx_Oracle
cd cx_Oracle
git submodule init
git submodule update
python setup.py install

Note that if you download a source zip file directly from GitHub then you will also need to download an ODPI-C source zip file and extract it inside the directory called “odpi”.

Install Using Source from PyPI

The source package can be downloaded manually from PyPI and extracted, after which the following commands should be run:

python setup.py build
python setup.py install

Install Oracle Client

Using cx_Oracle requires Oracle Client libraries to be installed. The libraries provide the necessary network connectivity allowing applications to access an Oracle Database instance. They also provide basic and advanced connection management and data features to cx_Oracle. cx_Oracle uses the shared library loading mechanism available on each supported platform to load the Oracle Client library at runtime. Oracle Client versions 12.2, 12.1 and 11.2 are supported.

The simplest Oracle Client is the free Oracle Instant Client. Only the “Basic” or “Basic Light” package is required. Oracle Client libraries are also available in any Oracle Database installation or full Oracle Client installation.

Make sure your library loading path, such as PATH on Windows, or LD_LIBRARY_PATH on Linux, is set to the location of the Oracle Client libraries. On macOS the libraries should be in ~/lib or /usr/local/lib.

On Windows, Microsoft Windows Redistributables matching the version of the Oracle client libraries need to be installed.

See ODPI-C installation instructions for details on configuration.

Oracle Database

Oracle Client libraries allow connection to older and newer databases. In summary, Oracle Client 12.2 can connect to Oracle Database 11.2 or greater. Oracle Client 12.1 can connect to Oracle Database 10.2 or greater. Oracle Client 11.2 can connect to Oracle Database 9.2 or greater. For additional information on which Oracle Database releases are supported by which Oracle client versions, please see Doc ID 207303.1.

Since a single cx_Oracle binary can use multiple client versions and access multiple database versions, it is important your application is tested in your intended release environments. Newer Oracle clients support new features, such as the oraaccess.xml external configuration file available with 12.1 or later clients, and session pool enhancements to dead connection detection in 12.2 clients.

The function clientversion() can be used to determine which Oracle Client version is in use and the attribute Connection.version can be used to determine which Oracle Database version a connection is accessing. These can then be used to adjust application behavior accordingly. Attempts to use some Oracle features that are not supported by a particular client/server combination may result in runtime errors. These include:

  • when attempting to access attributes that are not supported by the current Oracle Client library you will get the error “ORA-24315: illegal attribute type”
  • when attempting to use implicit results with Oracle Client 11.2 against Oracle Database 12c you will get the error “ORA-29481: Implicit results cannot be returned to client”
  • when attempting to get array DML row counts with Oracle Client 11.2 you will get the error “DPI-1013: not supported”

Troubleshooting

If installation fails:

  • Use option -v with pip. Review your output and logs. Try to install using a different method. Google anything that looks like an error. Try some potential solutions.
  • Was there a network connection error? Do you need to see the environment variables http_proxy and/or https_proxy?
  • Do you get the error “No module named pip”? The pip module is builtin to Python from version 2.7.9 but is sometimes removed by the OS. Use the venv module (builtin to Python 3.x) or virtualenv module (Python 2.x) instead.
  • Do you get the error “fatal error: dpi.h: No such file or directory” when building from source code? Ensure that your source installation has a subdirectory called “odpi” containing files. If missing, review the section on Install Using GitHub.

If importing cx_Oracle fails:

  • Do you get the error “DPI-1047: Oracle Client library cannot be loaded”?
    • Check that Python, cx_Oracle and your Oracle Client libraries are all 64-bit or all 32-bit. The DPI-1047 message will tell you whether the 64-bit or 32-bit Oracle Client is needed for your Python.
    • On Windows, restart your command prompt and use set PATH to check the environment variable has the correct Oracle Client listed before any other Oracle directories.
    • On Windows, use the DIR command on the directory set in PATH. Verify that OCI.DLL exists there.
    • On Windows, check that the correct Windows Redistributables have been installed.
    • On Linux, check the LD_LIBRARY_PATH environment variable contains the Oracle Client library directory.
    • On macOS, make sure Oracle Instant Client is in ~/lib or /usr/local/lib and that you are not using the bundled Python (use Homebrew or Python.org instead).
  • If you have both Python 2 and 3 installed, make sure you are using the correct python and pip (or python3 and pip3) executables.