2. Installing python-oracledb — python-oracledb 3.2.0b1 documentation (original) (raw)

The python-oracledb driver allows Python 3 applications to connect to Oracle Database.

The python-oracledb driver is the renamed, major version successor to cx_Oracle 8.3. For upgrade information, see Upgrading from cx_Oracle 8.3 to python-oracledb. The cx_Oracle driver is obsolete and should not be used for new development.

architecture of the python-oracledb driver

Fig. 2.1 Architecture of the python-oracledb driver

By default, python-oracledb runs in a ‘Thin’ mode which connects directly to Oracle Database. This mode does not need Oracle Client libraries. However, some additional functionality is available when python-oracledb uses them. Python-oracledb is said to be in ‘Thick’ mode when Oracle Client libraries are used. See Enabling python-oracledb Thick mode. Both modes have comprehensive functionality supporting the Python Database API v2.0 Specification.

2.1. Quick Start python-oracledb Installation

Python-oracledb is typically installed from Python’s package repositoryPyPI using pip.

  1. Install Python 3 if it is not already available.
    Use any version from Python 3.9 through 3.13.
    Previous versions of python-oracledb supported older Python versions.
  2. Install python-oracledb, for example:

python -m pip install oracledb --upgrade --user

Note the module name is simply oracledb.

On some platforms the Python binary may be called python3 instead ofpython.

If you are behind a proxy, use the --proxy option. For example:

python -m pip install oracledb --upgrade --user --proxy=http://proxy.example.com:80

By default, python-oracledb connects directly to Oracle Database. This lets it be used immediately without needing any additional installation of Oracle Client libraries.

  1. Create a file test.py such as:

import getpass

import oracledb

un = 'scott' cs = 'localhost/orclpdb' pw = getpass.getpass(f'Enter password for {un}@{cs}: ')

with oracledb.connect(user=un, password=pw, dsn=cs) as connection: with connection.cursor() as cursor: sql = """select sysdate from dual""" for r in cursor.execute(sql): print(r)

  1. Edit test.py and set the un and cs variables to your own database username and the database connection string, respectively.
    A simple connection to the database requires an Oracle Database user name and password and a databaseconnection string. For python-oracledb, a common connection string format is hostname:port/servicename, using the host name where the database is running, the Oracle Database service name of the database instance, and the port that the database is using. If the default port 1521 is being used, then this component of the connection string is often omitted.
    The database can be on-premises or in the Cloud. The python-oracledb driver does not include a database.
  2. Run the program:
    Enter the database password when prompted and the queried date will be shown, for example:
    Enter password for cj@localhost/orclpdb: xxxxxxxxxx
    (datetime.datetime(2024, 4, 30, 8, 24, 4),)

If you have trouble installing, refer to detailed instructions below, or seeTroubleshooting Errors.

You can learn more about python-oracledb from the python-oracledb documentationand samples.

2.2. Supported Oracle Database Versions

When python-oracledb is used in the default Thin mode, it connects directly to the Oracle Database and does not require Oracle Client libraries. Connections in this mode can be made to Oracle Database 12.1 or later.

To connect to older Oracle Database releases you must have Oracle Client libraries installed, and enable python-oracledb’s Thick mode.

In python-oracledb Thick mode, Oracle Database’s standard client-server network interoperability allows connections between different versions of Oracle Client libraries and Oracle Database. For current or previously certified configurations, see Oracle Support’s Doc ID 207303.1. In summary:

Any attempt to use Oracle Database features that are not supported by a particular mode or client library/database combination will result in runtime errors. The python-oracledb attribute Connection.thin can be used to see what mode a connection is in. In the Thick mode, the functionoracledb.clientversion() can be used to determine which Oracle Client version is in use. The attribute Connection.version can be used to determine which Oracle Database version a connection is accessing. These attributes can then be used to adjust the application behavior accordingly.

2.3. Installation Requirements

To use python-oracledb, you need:

2.4. Installing python-oracledb on Linux

This section discusses the generic installation methods on Linux.

2.4.1. Install python-oracledb

The generic way to install python-oracledb on Linux is to use Python’s pip package to install from Python’s package repository PyPI:

python -m pip install oracledb --upgrade

This will download and install a pre-compiled binary from PyPI if one is available for your architecture. Otherwise, the source will be downloaded, compiled, and the resulting binary installed. Compiling python-oracledb requires thePython.h header file. If you are using the default python package, this file is in the python-devel package or equivalent.

On some platforms the Python binary may be called python3 instead ofpython. For example, to use the default Python 3.6 installation on Oracle Linux 8, install with:

python3 -m pip install oracledb --upgrade

Note it is recommended to use a more recent version Python, see Python for Oracle Linux.

The installation --user option is useful when you do not have permission to write to system directories:

python3 -m pip install oracledb --upgrade --user

If you are behind a proxy, use the --proxy option. For example:

python -m pip install oracledb --upgrade --proxy=http://proxy.example.com:80

2.4.2. Optionally Install Oracle Client

By default, python-oracledb runs in a Thin mode which connects directly to Oracle Database so no further installation steps are required. However, to use additional features available in Thick mode you need Oracle Client libraries installed. Oracle Client versions 23, 21, 19, 18, 12 and 11.2 are supported.

To use python-oracledb in Thick mode you must calloracledb.init_oracle_client() in your application, seeEnabling python-oracledb Thick mode. For example:

import oracledb

oracledb.init_oracle_client()

On Linux, do not pass the lib_dir parameter toinit_oracle_client(). The Oracle Client libraries on Linux must be in the system library search path before the Python process starts.

2.4.2.1. Oracle Instant Client Zip Files

To use python-oracledb Thick mode with Oracle Instant Client zip files:

  1. Download an Oracle 23, 21, 19, 18, 12, or 11.2 “Basic” or “Basic Light” zip file matching your Python 64-bit or 32-bit architecture:

Oracle Instant Client 23ai will connect to Oracle Database 19 or later. Oracle Instant Client 21c will connect to Oracle Database 12.1 or later. Oracle Instant Client 19c will connect to Oracle Database 11.2 or later.

It is recommended to keep up to date with the latest Oracle Instant Client release updates of your desired major version. Oracle Database 23ai and 19c are Long Term Support Releases whereas Oracle Database 21c is an Innovation Release.

Note Oracle Database 23ai 32-bit clients are not available on any platform, however, you can use older 32-bit clients to connect to Oracle Database 23ai.

  1. Unzip the package into a single directory that is accessible to your application. For example:
    mkdir -p /opt/oracle
    cd /opt/oracle
    unzip instantclient-basic-linux.x64-21.6.0.0.0.zip
    Note OS restrictions may prevent the opening of Oracle Client libraries installed in unsafe paths, such as from a user directory. You may need to install under a directory like /opt or /usr/local.
  2. Install the libaio package with sudo or as the root user. For example:
    On some Linux distributions this package is called libaio1 instead.
    When using Oracle Instant Client 19 on recent Linux versions such as Oracle Linux 8, you may need to manually install the libnsl package to makelibnsl.so available.
  3. If there is no other Oracle software on the machine that will be impacted, permanently add Instant Client to the runtime link path. For example, with sudo or as the root user:
    sudo sh -c "echo /opt/oracle/instantclient_21_6 > /etc/ld.so.conf.d/oracle-instantclient.conf"
    sudo ldconfig
    Alternatively, set the environment variable LD_LIBRARY_PATH to the appropriate directory for the Instant Client version. For example:
    export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_6:$LD_LIBRARY_PATH

Make sure this is set in each shell that invokes Python. Web servers and other daemons commonly reset environment variables so using ldconfig is generally preferred instead.

  1. If you use optional Oracle configuration files such as tnsnames.ora,sqlnet.ora, or oraaccess.xml with Instant Client, then put the files in an accessible directory, for example in/opt/oracle/your_config_dir. Then use:
    import oracledb
    oracledb.init_oracle_client(config_dir="/home/your_username/oracle/your_config_dir")
    or set the environment variable TNS_ADMIN to that directory name.
    Alternatively, put the files in the network/admin subdirectory of Instant Client, for example in /opt/oracle/instantclient_21_6/network/admin. This is the default Oracle configuration directory for executables linked with this Instant Client.
  2. Call oracledb.init_oracle_client() in your application, if it is not already used.

2.4.2.2. Oracle Instant Client RPMs

To use python-oracledb with Oracle Instant Client RPMs:

  1. Download an Oracle 23, 21, 19, 18, 12, or 11.2 “Basic” or “Basic Light” RPM matching your Python architecture:
  1. Install the downloaded RPM with sudo or as the root user. For example:
    sudo yum install oracle-instantclient-basic-21.6.0.0.0-1.x86_64.rpm
    Yum will automatically install required dependencies, such as libaio.
    When using Oracle Instant Client 19 on recent Linux versions such as Oracle Linux 8, you may need to manually install the libnsl package to makelibnsl.so available.
  2. For Instant Client 19 or later, the system library search path is automatically configured during installation.
    For older versions, if there is no other Oracle software on the machine that will be impacted, permanently add Instant Client to the runtime link path. For example, with sudo or as the root user:
    sudo sh -c "echo /usr/lib/oracle/18.5/client64/lib > /etc/ld.so.conf.d/oracle-instantclient.conf"
    sudo ldconfig
    Alternatively, for version 18 and earlier, every shell running Python will need to have the environment variableLD_LIBRARY_PATH set to the appropriate directory for the Instant Client version. For example:
    export LD_LIBRARY_PATH=/usr/lib/oracle/18.5/client64/lib:$LD_LIBRARY_PATH

Web servers and other daemons commonly reset environment variables so usingldconfig is generally preferred instead.

  1. If you use optional Oracle configuration files such as tnsnames.ora,sqlnet.ora or oraaccess.xml with Instant Client, then put the files in an accessible directory, for example in/opt/oracle/your_config_dir. Then your application code can use:
    import oracledb
    oracledb.init_oracle_client(config_dir="/opt/oracle/your_config_dir")
    or you can set the environment variable TNS_ADMIN to that directory name.
    Alternatively, put the files in the network/admin subdirectory of Instant Client, for example in /usr/lib/oracle/21/client64/lib/network/admin. This is the default Oracle configuration directory for executables linked with this Instant Client.
  2. Call oracledb.init_oracle_client() in your application, if it is not already used.

2.4.2.3. Local Database or Full Oracle Client

Python-oracledb applications can use Oracle Client 23, 21, 19, 18, 12, or 11.2 libraries from a local Oracle Database or full Oracle Client installation (such as installed by Oracle’s GUI installer).

The libraries must be either 32-bit or 64-bit, matching your Python architecture. Note Oracle Database 23ai 32-bit clients are not available on any platform, however, you can use older 32-bit clients to connect to Oracle Database 23ai.

  1. Set required Oracle environment variables by running the Oracle environment script. For example:
    source /usr/local/bin/oraenv
    For Oracle Database Express Edition (“XE”) 11.2, run:
    source /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh
  2. Optional Oracle configuration files such as tnsnames.ora, sqlnet.ora, or oraaccess.xml can be placed in $ORACLE_HOME/network/admin.
    Alternatively, Oracle configuration files can be put in another, accessible directory. Then set the environment variable TNS_ADMIN to that directory name.
  3. Call oracledb.init_oracle_client() in your application, if it is not already used.

2.5. Installing python-oracledb on Windows

2.5.1. Install python-oracledb

Use Python’s pip package to install python-oracledb from Python’s package repository PyPI:

python -m pip install oracledb --upgrade

If you are behind a proxy, use the --proxy option. For example:

python -m pip install oracledb --upgrade --proxy=http://proxy.example.com:80

This will download and install a pre-compiled binary if one is available for your architecture. If a pre-compiled binary is not available, the source will be downloaded, compiled, and the resulting binary installed.

2.5.2. Optionally Install Oracle Client

By default, python-oracledb runs in a Thin mode which connects directly to Oracle Database so no further installation steps are required. However, to use additional features available in Thick mode you need Oracle Client libraries installed. Oracle Client versions 21, 19, 18, 12, and 11.2 are supported.

To use python-oracledb in Thick mode you must calloracledb.init_oracle_client() in your application, seeEnabling python-oracledb Thick mode. For example:

import oracledb

oracledb.init_oracle_client()

On Windows, you may prefer to pass the lib_dir parameter in the call as shown below.

2.5.2.1. Oracle Instant Client Zip Files

To use python-oracledb in Thick mode with Oracle Instant Client zip files:

  1. Download an Oracle 21, 19, 18, 12, or 11.2 “Basic” or “Basic Light” zip file: 64-bitor 32-bit, matching your Python architecture. Note Oracle Database 23ai 32-bit clients are not available on any platform, however, you can use older 32-bit clients to connect to Oracle Database 23ai.
    The latest version is recommended. Oracle Instant Client 19 will connect to Oracle Database 11.2 or later.
  2. Unzip the package into a directory that is accessible to your application. For example unzipinstantclient-basic-windows.x64-19.22.0.0.0dbru.zip toC:\oracle\instantclient_19_22.
  3. Oracle Instant Client libraries require a Visual Studio redistributable with a 64-bit or 32-bit architecture to match Instant Client’s architecture. Each Instant Client version requires a different redistributable version:
2.5.2.1.1. Configure Oracle Instant Client
  1. There are several alternative ways to tell python-oracledb where your Oracle Client libraries are, see Initializing python-oracledb.
  1. If you use optional Oracle configuration files such as tnsnames.ora,sqlnet.ora, or oraaccess.xml with Instant Client, then put the files in an accessible directory, for example inC:\oracle\your_config_dir. Then use:
    import oracledb
    oracledb.init_oracle_client(lib_dir=r"C:\oracle\instantclient_19_22",
    config_dir=r"C:\oracle\your_config_dir")

or set the environment variable TNS_ADMIN to that directory name.
Alternatively, put the files in a network\admin subdirectory of Instant Client, for example in C:\oracle\instantclient_19_22\network\admin. This is the default Oracle configuration directory for executables linked with this Instant Client.

2.5.2.2. Local Database or Full Oracle Client

Python-oracledb Thick mode applications can use Oracle Client 21, 19, 18, 12, or 11.2 libraries from a local Oracle Database or full Oracle Client (such as installed by Oracle’s GUI installer).

The Oracle libraries must be either 32-bit or 64-bit, matching your Python architecture. Note Oracle Database 23ai 32-bit clients are not available on any platform, however, you can use older 32-bit clients to connect to Oracle Database 23ai.

  1. Set the environment variable PATH to include the path that containsOCI.DLL, if it is not already set.
    Restart any open command prompt windows.
  2. Optional Oracle configuration files such as tnsnames.ora,sqlnet.ora, or oraaccess.xml can be placed in thenetwork\admin subdirectory of the Oracle Database software installation.
    Alternatively, pass config_dir to oracledb.init_oracle_client()as shown in the previous section, or set TNS_ADMIN to the directory name.
  3. To use python-oracledb in Thick mode you must calloracledb.init_oracle_client() in your application, seeEnabling python-oracledb Thick mode.
    import oracledb
    oracledb.init_oracle_client()

2.6. Installing python-oracledb on macOS

Python-oracledb is available as a Universal binary for Python 3.9, or later, on Apple macOS Intel x86-64 and Apple macOS ARM64 (M1, M2, M3, M4) architectures.

2.6.1. Install python-oracledb

Use Python’s pip package to install python-oracledb from Python’s package repository PyPI:

python -m pip install oracledb --upgrade

The --user option may be useful if you do not have permission to write to system directories:

python -m pip install oracledb --upgrade --user

If you are behind a proxy, use the --proxy option. For example:

python -m pip install oracledb --upgrade --user --proxy=http://proxy.example.com:80

To install into the system Python, you may need to use /usr/bin/python3instead of python:

/usr/bin/python3 -m pip install oracledb --upgrade --user

2.6.2. Optionally Install Oracle Client

By default, python-oracledb runs in a Thin mode which connects directly to Oracle Database so no further installation steps are required. However, to use additional features available in Thick mode you need Oracle Client libraries installed.

You can get the libraries from either the Oracle Instant Client Basic orBasic Light package. The steps below show installing Basic.

2.6.2.1. Instant Client Scripted Installation on macOS ARM64

Instant Client installation can be scripted. Open a terminal window and run:

cd $HOME/Downloads curl -O https://download.oracle.com/otn_software/mac/instantclient/233023/instantclient-basic-macos.arm64-23.3.0.23.09.dmg hdiutil mount instantclient-basic-macos.arm64-23.3.0.23.09.dmg /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09/install_ic.sh hdiutil unmount /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09

Note you should use the latest DMG available.

If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh once. It will copy all mounted Instant Client DMG packages at the same time.

The Instant Client directory will be like$HOME/Downloads/instantclient_23_3. Applications may not have access to the Downloads directory, so you should move Instant Client somewhere convenient.

2.6.2.2. Instant Client Manual Installation on macOS ARM64

If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh once. It will copy all mounted Instant Client DMG packages at the same time.

2.6.2.3. Instant Client Scripted Installation on macOS Intel x86-64

Instant Client installation can be scripted. Open a terminal window and run:

cd $HOME/Downloads curl -O https://download.oracle.com/otn_software/mac/instantclient/1916000/instantclient-basic-macos.x64-19.16.0.0.0dbru.dmg hdiutil mount instantclient-basic-macos.x64-19.16.0.0.0dbru.dmg /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru/install_ic.sh hdiutil unmount /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru

Note you should use the latest DMG available.

If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh once. It will copy all mounted Instant Client DMG packages at the same time.

The Instant Client directory will be $HOME/Downloads/instantclient_19_16. Applications may not have access to the Downloads directory, so you should move Instant Client somewhere convenient.

2.6.2.4. Instant Client Manual Installation on macOS Intel x86-64

If you have multiple Instant Client DMG packages mounted, you only need to runinstall_ic.sh once. It will copy all mounted Instant Client DMG packages at the same time.

2.6.3. Configure Oracle Instant Client

Your application must load the installed Oracle Instant Client libraries. It can optionally indicate external configuration files.

  1. Call oracledb.init_oracle_client() in your application:
    import oracledb
    oracledb.init_oracle_client(lib_dir="/Users/your_username/Downloads/instantclient_23_3")
  2. If you use optional Oracle configuration files such as tnsnames.ora,sqlnet.ora, or oraaccess.xml with Oracle Instant Client, then put the files in an accessible directory, for example in/Users/your_username/oracle/your_config_dir. Then use:
    import oracledb
    oracledb.init_oracle_client(lib_dir="/Users/your_username/Downloads/instantclient_23_3",
    config_dir="/Users/your_username/oracle/your_config_dir")

Or set the environment variable TNS_ADMIN to that directory name.
Alternatively, put the files in the network/admin subdirectory of Oracle Instant Client, for example in/Users/your_username/Downloads/instantclient_23_3/network/admin. This is the default Oracle configuration directory for executables linked with this Instant Client.

2.7. Installing python-oracledb without Internet Access

To install python-oracledb on a computer that is not connected to the internet, download a python-oracledb wheel package from Python’s package repository PyPI. Use the file appropriate for your operating system and python version. Transfer this file to the offline computer and install it with:

python -m pip install ""

You will also need to use a similar step to install the required cryptography package and its dependencies.

Then follow the general python-oracledb platform installation instructions to install Oracle Client libraries. This is only necessary if you intend to use python-oracledb Thick mode.

2.8. Installing python-oracledb without the Cryptography Package

If the Python cryptography package is not available, python-oracledb can still be installed but can only be used in Thick mode. Trying to use Thin mode will give the error DPY-3016: python-oracledb thin mode cannot be used because the cryptography package is not installed.

To use python-oracledb without the cryptography package:

2.9. Installing from Source Code

For platforms that do not have pre-built binaries on PyPI, using the normal python -m pip install oracledb command will download the python-oracledb source bundle, build, and install it.

Alternatively, to create your own package files for installation, you can build and install python-oracledb either locally from source code, or by using a presupplied GitHub Action which builds packages for all architectures and Python versions.

2.9.1. Building a python-oracledb package locally

  1. Install a C99 compliant C compiler.
  2. Download the source code using one of the following options:
  3. With the source code available, build a python-oracledb package by running:
    cd python-oracledb # the name may vary depending on the download
    python -m pip install build --upgrade

export PYO_COMPILE_ARGS='-g0' # optionally set any compilation arguments

python -m build
A python-oracledb wheel package is created in the dist subdirectory. For example when using Python 3.12 on macOS you might have the filedist/oracledb-3.1.0-cp312-cp312-macosx_14_0_arm64.whl. 4. Install this package:
python -m pip install dist/oracledb-3.1.0-cp312-cp312-macosx_14_0_arm64.whl
The package can also be installed on any computer which has the same architecture and Python version as the build machine.

2.9.2. Building python-oracledb packages using GitHub Actions

The python-oracledb GitHub repository has a builder Action that uses GitHub infrastructure to build python-oracledb packages for all architectures and Python versions.

  1. Fork the python-oracledb repository. Additionally fork theODPI-C repository, keeping the default name.
  2. Optionally edit .github/workflows/build.yaml and remove platforms and versions that you are not interested in. Building all packages can take some time.
  3. In your python-oracledb fork, go to the Actions tabhttps://github.com/<your name>/python-oracledb/actions/. If this is your first time using Actions, confirm enabling them.
  4. In the “All workflows” list on the left-hand side, select the “build” entry.
  5. Navigate to the “Run workflow” drop-down, select the branch to build from (for example, “main”), and run the workflow.
  6. When the build has completed, download the “python-oracledb-wheels” artifact, unzip it, and install the one for your architecture and Python version. For example, when using Python 3.12 on macOS, install:
    python -m pip install oracledb-3.1.0-cp312-cp312-macosx_10_13_universal2.whl

2.10. Installing Centralized Configuration Provider Modules for python-oracledb

To use python-oracledb with a centralized configuration provider, you must install the necessary modules for your preferred provider as detailed below.

2.10.1. Install Modules for the OCI Object Storage Centralized Configuration Provider

For python-oracledb to use an Oracle Cloud Infrastructure (OCI) Object Storage configuration provider, you must install theOCI package:

python -m pip install oci

See Using an OCI Object Storage Centralized Configuration Provider for information on using this configuration provider with python-oracledb.

2.10.2. Install Modules for the Azure App Centralized Configuration Provider

For python-oracledb to use an Azure App Configuration Provider, you must install the Azure App Configuration, Azure Core, and Azure Identity packages:

python -m pip install azure-appconfiguration azure-core azure-identity

If your password is stored in the Azure Key vault, then you additionally need to install the Azure Key Vault Secrets package:

python -m pip install azure-keyvault-secrets

See Using an Azure App Centralized Configuration Provider for information on using this configuration provider with python-oracledb.

2.11. Installing Cloud Native Authentication Modules for python-oracledb

To use a python-oracledb Cloud Native Authentication plugin, you must install the necessary modules for your preferred plugin, as detailed below.

2.11.1. Install Modules for the OCI Cloud Native Authentication Plugin

For python-oracledb to use the OCI Cloud Native Authentication Plugin, you must install the Python SDK for Oracle Cloud Infrastructure package:

python -m pip install oci

Review the OCI SDK installation instructionsas needed.

See OCI Cloud Native Authentication with the oci_tokens Plugin for more information on using the plugin in python-oracledb.

2.11.2. Install Modules for the Azure Cloud Native Authentication Plugin

For python-oracledb to use the Azure Cloud Native Authentication Plugin, you must install the Microsoft Authentication Library (MSAL) for Python package:

python -m pip install msal

Review the Microsoft MSAL installation instructionsas needed.

See Azure Cloud Native Authentication with the azure_tokens Plugin for more information on using the plugin in python-oracledb.