cx_Oracle 6 Installation¶
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
- On Linux, cx_Oracle 6 no longer uses Instant Client RPMs automatically. You must set
ldconfigto 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
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 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.
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”
If installation fails:
- Use option
-vwith 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
- 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 the
PATHenvironment variable on Windows. Ensure that you have restarted your command prompt if you have modified environment variables.
- Check the
LD_LIBRARY_PATHenvironment variable on Linux.
- On macOS, make sure Oracle Instant Client is in
/usr/local/liband that you are not using the bundled Python (use Homebrew or Python.org instead).
- Check that Python, cx_Oracle and your Oracle Client libraries are all 64-bit or all 32-bit.
- on Windows, check that the correct Windows Redistributables have been installed.
- If you have both Python 2 and 3 installed, make sure you are using the correct python and pip (or python3 and pip3) executables.