Install Python and the python-oracledb Driver

To connect to Autonomous Database from your Python application, install Python and the python-oracledb driver.

  1. Install Python 3, if it is not already available.

    The version of Python you use depends on your client-side OS and hardware. For example Windows, Linux, macOS, and others.


    Oracle recommends you keep up to date with Python and python-oracledb driver releases.
  2. Install the python-oracledb driver from PyPI.

    The python-oracledb driver is a Python programming language extension module allowing Python programs to connect to Oracle Database. The python-oracledb driver is the renamed, new major release of the popular cx_Oracle driver.

    Supported python-oracledb driver versions: python-oracledb 1.0 (or later)

    Run the following command to upgrade python:

    python -m pip install oracledb --upgrade

    You should see output similar to the following:

    Collecting oracledb
      Downloading oracledb-1.0.3-cp310-cp310-win_amd64.whl (1.0 MB)
         ---------------------------------------- 1.0/1.0 MB 1.8 MB/s eta 0:00:00
    Collecting cryptography>=3.4
      Downloading cryptography-37.0.4-cp36-abi3-win_amd64.whl (2.4 MB)
         ---------------------------------------- 2.4/2.4 MB 3.5 MB/s eta 0:00:00
    Collecting cffi>=1.12
      Downloading cffi-1.15.1-cp310-cp310-win_amd64.whl (179 kB)
         ---------------------------------------- 179.1/179.1 kB 5.4 MB/s eta 0:00:00
    Collecting pycparser
      Downloading pycparser-2.21-py2.py3-none-any.whl (118 kB)
         ---------------------------------------- 118.7/118.7 kB 7.2 MB/s eta 0:00:00
    Installing collected packages: pycparser, cffi, cryptography, oracledb
    Successfully installed cffi-1.15.1 cryptography-37.0.4 oracledb-1.0.3 pycparser-2.21

    Notes for installing python-oracledb:

    • If you are behind a proxy, use the --proxy option to add a proxy server to the command. For example:

      python -m pip install oracledb --upgrade --proxy=
    • In the case where you do not have permission to write to system directories, include the --user option. For example:

      python -m pip install oracledb --upgrade --user
    • If a binary package is not available for your platform, running pip will download the source package instead. The source is compiled and the resulting binary is installed.

    See Installing python-oracledb for additional options and tips.

  3. If you want to use the python-oracledb driver in Thick mode, install Oracle Client software.

    By default, python-oracledb runs in Thin mode which connects directly to Oracle Database. Thin mode does not require Oracle Client libraries. However, some additional functionality is available when python-oracledb runs in Thick mode.


    See Oracle Database Features Supported by python-oracledb for information on supported features in python-oracledb Thin and Thick modes. Not all of the features shown in this link are available with Autonomous Database.

    Python-oracledb uses Thick mode when you use either the Oracle Instant client libraries or the Oracle Database Client libraries and you call oracledb.init_oracle_client() in your Python code.

    When you install Oracle Client Software, there are differences in required minimum versions for mTLS and TLS connections, as follows:

    • Mutual TLS (mTLS) Connections:

      • If your database is on a remote computer, then download the free Oracle Instant Client “Basic” or “Basic Light” package for your operating system architecture. Use a supported version: Oracle Instant Client: 18.19 (or later), 19.2 (or later), or 21 (base release or later).

      • Alternatively, you can use the Full Oracle Database client libraries when they are available on your system (including Full Oracle Database Client: Oracle Database Client: 18.19 (or later), 19.2 (or later), or 21 (base release or later).

    • TLS Connections: Oracle Call Interface (OCI) clients support TLS authentication without a wallet if you are using the following client versions:

      • Oracle Instant Client/Oracle Database Client 19.14 (or later) and 21.5 (or later) - only on Linux x64 and Windows
      • Alternatively, you can use the Full Oracle Database client libraries when they are available on your system, including Full Oracle Database Client 19.14 (or later) and 21.5 (or later).