2.Installing python-oracledb

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

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

architecture of the python-oracledb driver

Fig. 2.1Architecture of the python-oracledb driver

By default, python-oracledb runs in a ‘Thin’ mode which connects directly toOracle Database. This mode does not need Oracle Client libraries. However,someadditional functionality is available whenpython-oracledb uses them. Python-oracledb is said to be in ‘Thick’ mode whenOracle Client libraries are used. SeeEnabling python-oracledb Thick mode. Both modes havecomprehensive functionality supporting the Python Database API v2.0Specification.

2.1.Quick Start python-oracledb Installation

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

  1. InstallPython 3 if it is not alreadyavailable.

    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-mpipinstalloracledb--upgrade--user

Note the module name is simplyoracledb.

On some platforms the Python binary may be calledpython3 instead ofpython.

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

python-mpipinstalloracledb--upgrade--user--proxy=http://proxy.example.com:80

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

  1. Create a filetest.py such as:

importoracledbimportgetpassun="scott"cs="localhost/orclpdb"# cs = "localhost/freepdb1"   # for Oracle Database Free users# cs = "localhost/orclpdb1"   # some databases may have this servicepw=getpass.getpass(f"Enter password for{un}@{cs}: ")withoracledb.connect(user=un,password=pw,dsn=cs)asconnection:withconnection.cursor()ascursor:sql="select sysdate from dual"forrincursor.execute(sql):print(r)

  1. Edittest.py and set theun andcs variables to your owndatabase username and the database connection string, respectively.

    A simpleconnection to the database requires an OracleDatabaseuser name and password and a databaseconnection string. For python-oracledb, a commonconnection string format ishostname:port/servicename, using the hostname where the database is running, the Oracle Database service name of thedatabase instance, and the port that the database is using. If the defaultport 1521 is being used, then this component of the connection string isoften omitted.

    The database can be on-premises or in theCloud. Thepython-oracledb driver does not include a database.

  2. Run the program:

    pythontest.py

    Enter the database password when prompted and the queried date will be shown,for example:

    Enterpasswordforcj@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 thepython-oracledbdocumentationandsamples.

2.2.Supported Oracle Database Versions

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

To connect to older Oracle Database releases you must have Oracle Clientlibraries installed, and enable python-oracledb’sThick mode.

In python-oracledb Thick mode, Oracle Database’s standard client-server networkinteroperability allows connections between different versions of Oracle Clientlibraries and Oracle Database. For current or previously certifiedconfigurations, see Oracle Support’sDoc ID 207303.1.In summary:

  • Oracle Client 23 can connect to Oracle Database 19 or later

  • Oracle Client 21 can connect to Oracle Database 12.1 or later

  • Oracle Client 19, 18 and 12.2 can connect to Oracle Database 11.2 or later

  • Oracle Client 12.1 can connect to Oracle Database 10.2 or later

  • Oracle Client 11.2 can connect to Oracle Database 9.2 or later

Any attempt to use Oracle Database features that are not supported by aparticular mode or client library/database combination will result in runtimeerrors. The python-oracledb attributeConnection.thin can be used tosee what mode a connection is in. In the Thick mode, the functionoracledb.clientversion() can be used to determine which Oracle Clientversion is in use. The attributeConnection.version can be used todetermine which Oracle Database version a connection is accessing. Theseattributes can then be used to adjust the application behavior accordingly.

2.3.Installation Requirements

To use python-oracledb, you need:

  • Python 3.9, 3.10, 3.11, 3.12 or 3.13

  • The Python cryptography package. This package is automatically installed as adependency of python-oracledb. It is strongly recommended that you keep thecryptography package up to date whenever new versions are released. If thecryptography package is not available, you can still install python-oracledbbut can only use it in Thick mode, seeInstalling python-oracledb without the Cryptography Package.

  • Optionally, Oracle Client libraries can be installed to enable someadditional advanced functionality. These can be from the freeOracle InstantClientBasic or Basic Light packages, from a full Oracle Client installation (suchas installed by Oracle’s GUI installer), or from those included in OracleDatabase if Python is on the same machine as the database. Oracle Clientlibraries versions 23, 21, 19, 18, 12, and 11.2 are supported where availableon Linux, Windows and macOS. Oracle’s standard client-server versioninteroperability allows connection to both older and newer databases.

  • An Oracle Database either local or remote, on-premises or in the Cloud.

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’spip package to install from Python’s packagerepositoryPyPI:

python-mpipinstalloracledb--upgrade

This will download and install a pre-compiled binary fromPyPI if one is available for yourarchitecture. Otherwise, the source will be downloaded, compiled, and theresulting binary installed. Compiling python-oracledb requires thePython.h header file. If you are using the defaultpython package,this file is in thepython-devel package or equivalent.

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

python3-mpipinstalloracledb--upgrade

Note it is recommended to use a more recent version Python, seePython forOracle Linux.

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

python3-mpipinstalloracledb--upgrade--user

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

python-mpipinstalloracledb--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 toOracle Database so no further installation steps are required. However, to useadditional features available inThick mode you needOracle Client libraries installed. Oracle Client versions 23, 21, 19, 18, 12and 11.2 are supported.

  • If your database is on a remote computer, then download the freeOracleInstant Client “Basic”or “Basic Light” package for your operating system architecture.

  • Alternatively, use the client libraries already available in a locallyinstalled database such as the freeOracle Database 23ai Free release.

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

importoracledboracledb.init_oracle_client()

On Linux, do not pass thelib_dir parameter toinit_oracle_client(). The Oracle Client libraries on Linuxmust be in the system library search pathbefore 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” zipfile 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 Clientrelease updates of your desired major version. Oracle Database 23ai and 19care Long Term Support Releases whereas Oracle Database 21c is an InnovationRelease.

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 yourapplication. For example:

    mkdir-p/opt/oraclecd/opt/oracleunzipinstantclient-basic-linux.x64-21.6.0.0.0.zip

    Note OS restrictions may prevent the opening of Oracle Client librariesinstalled in unsafe paths, such as from a user directory. You may need toinstall under a directory like/opt or/usr/local.

  2. Install thelibaio package with sudo or as the root user. For example:

    sudoyuminstalllibaio

    On some Linux distributions this package is calledlibaio1 instead.

    When using Oracle Instant Client 19 on recent Linux versions such as OracleLinux 8, you may need to manually install thelibnsl package to makelibnsl.so available.

  3. If there is no other Oracle software on the machine that will beimpacted, permanently add Instant Client to the runtime linkpath. For example, with sudo or as the root user:

    sudosh-c"echo /opt/oracle/instantclient_21_6 > /etc/ld.so.conf.d/oracle-instantclient.conf"sudoldconfig

    Alternatively, set the environment variableLD_LIBRARY_PATH tothe appropriate directory for the Instant Client version. Forexample:

    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 andother daemons commonly reset environment variables so usingldconfig isgenerally preferred instead.

  1. If you use optional Oracle configuration files such astnsnames.ora,sqlnet.ora, ororaaccess.xml with Instant Client, then put the filesin an accessible directory, for example in/opt/oracle/your_config_dir. Then use:

    importoracledboracledb.init_oracle_client(config_dir="/home/your_username/oracle/your_config_dir")

    or set the environment variableTNS_ADMIN to that directory name.

    Alternatively, put the files in thenetwork/admin subdirectory of InstantClient, for example in/opt/oracle/instantclient_21_6/network/admin.This is the default Oracle configuration directory for executables linkedwith this Instant Client.

  2. Calloracledb.init_oracle_client() in your application, if it is notalready 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” RPMmatching your Python architecture:

Alternatively, Oracle’s yum server has convenient repositories, seeOracleDatabase Instant Client for Oracle Linux instructions. Therepositories are:

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 Clientrelease updates of your desired major version. Oracle Database 23ai and 19care Long Term Support Releases whereas Oracle Database 21c is an InnovationRelease.

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. Install the downloaded RPM with sudo or as the root user. For example:

    sudoyuminstalloracle-instantclient-basic-21.6.0.0.0-1.x86_64.rpm

    Yum will automatically install required dependencies, such aslibaio.

    When using Oracle Instant Client 19 on recent Linux versions such as OracleLinux 8, you may need to manually install thelibnsl package to makelibnsl.so available.

  2. For Instant Client 19 or later, the system library search path isautomatically configured during installation.

    For older versions, if there is no other Oracle software on the machine thatwill be impacted, permanently add Instant Client to the runtime linkpath. For example, with sudo or as the root user:

    sudosh-c"echo /usr/lib/oracle/18.5/client64/lib > /etc/ld.so.conf.d/oracle-instantclient.conf"sudoldconfig

    Alternatively, for version 18 and earlier, every shell runningPython will need to have the environment variableLD_LIBRARY_PATH set to the appropriate directory for theInstant 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 astnsnames.ora,sqlnet.ora ororaaccess.xml with Instant Client, then put the filesin an accessible directory, for example in/opt/oracle/your_config_dir. Then your application code can use:

    importoracledboracledb.init_oracle_client(config_dir="/opt/oracle/your_config_dir")

    or you can set the environment variableTNS_ADMIN to that directoryname.

    Alternatively, put the files in thenetwork/admin subdirectory of InstantClient, for example in/usr/lib/oracle/21/client64/lib/network/admin.This is the default Oracle configuration directory for executables linkedwith this Instant Client.

  2. Calloracledb.init_oracle_client() in your application, if it is notalready 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.2libraries from a local Oracle Database or full Oracle Client installation (suchas installed by Oracle’s GUI installer).

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

  1. Set required Oracle environment variables by running the Oracle environmentscript. 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 astnsnames.ora,sqlnet.ora,ororaaccess.xml can be placed in$ORACLE_HOME/network/admin.

    Alternatively, Oracle configuration files can be put in another, accessibledirectory. Then set the environment variableTNS_ADMIN to thatdirectory name.

  3. Calloracledb.init_oracle_client() in your application, if it is notalready used.

2.5.Installing python-oracledb on Windows

2.5.1.Install python-oracledb

Use Python’spip packageto install python-oracledb from Python’s package repositoryPyPI:

python-mpipinstalloracledb--upgrade

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

python-mpipinstalloracledb--upgrade--proxy=http://proxy.example.com:80

This will download and install a pre-compiled binaryif one is available for your architecture. If apre-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 toOracle Database so no further installation steps are required. However, to useadditional features available inThick mode you needOracle Client libraries installed. Oracle Client versions 21, 19, 18, 12, and11.2 are supported.

  • If your database is on a remote computer, then download the freeOracleInstant Client “Basic”or “Basic Light” package for your operating system architecture.

  • Alternatively, use the client libraries already available in a locallyinstalled database such as the freeOracle Database Express Edition (“XE”) release.

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

importoracledboracledb.init_oracle_client()

On Windows, you may prefer to pass thelib_dir parameter in the call asshown 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” zipfile:64-bitor32-bit,matching your Python architecture. Note Oracle Database 23ai 32-bit clientsare not available on any platform, however, you can use older 32-bit clientsto connect to Oracle Database 23ai.

    The latest version is recommended. Oracle Instant Client 19 will connect toOracle Database 11.2 or later.

  2. Unzip the package into a directory that is accessible to yourapplication. 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 witha 64-bit or 32-bit architecture to match Instant Client’s architecture.Each Instant Client version requires a different redistributable version:

  • For Instant Client 21, installVS 2019 or later

  • For Instant Client 19, installVS 2017

  • For Instant Client 18 or 12.2, installVS 2013

  • For Instant Client 12.1, installVS 2010

  • For Instant Client 11.2, installVS 2005 64-bit

2.5.2.1.1.Configure Oracle Instant Client

  1. There are several alternative ways to tell python-oracledb where your OracleClient libraries are, seeInitializing python-oracledb.

  • With Oracle Instant Client you can useoracledb.init_oracle_client() in your application, for example:

    importoracledboracledb.init_oracle_client(lib_dir=r"C:\oracle\instantclient_19_22")

    Note that a ‘raw’ string is used because backslashes occur in the path.

  • Alternatively, add the Oracle Instant Client directory to thePATHenvironment variable. The directory must occur inPATH before anyother Oracle directories. Restart any open command prompt windows.

    Update your application to callinit_oracle_client(), which enablespython-oracledb Thick mode:

    importoracledboracledb.init_oracle_client()

  • Another way to setPATH is to use a batch file that sets it beforePython is executed, for example:

    REMmypy.batSETPATH=C:\oracle\instantclient_19_22;%PATH%python%*

    Invoke this batch file every time you want to run Python.

    Update your application to callinit_oracle_client(), which enablespython-oracledb Thick mode:

    importoracledboracledb.init_oracle_client()

  1. If you use optional Oracle configuration files such astnsnames.ora,sqlnet.ora, ororaaccess.xml with Instant Client, then put the filesin an accessible directory, for example inC:\oracle\your_config_dir. Then use:

    importoracledboracledb.init_oracle_client(lib_dir=r"C:\oracle\instantclient_19_22",config_dir=r"C:\oracle\your_config_dir")

    or set the environment variableTNS_ADMIN to that directory name.

    Alternatively, put the files in anetwork\admin subdirectory of InstantClient, for example inC:\oracle\instantclient_19_22\network\admin.This is the default Oracle configuration directory for executables linkedwith 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 asinstalled by Oracle’s GUI installer).

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

  1. Set the environment variablePATH 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 astnsnames.ora,sqlnet.ora, ororaaccess.xml can be placed in thenetwork\admin subdirectory of the Oracle Database softwareinstallation.

    Alternatively, passconfig_dir tooracledb.init_oracle_client()as shown in the previous section, or setTNS_ADMIN to the directoryname.

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

    importoracledboracledb.init_oracle_client()

2.6.Installing python-oracledb on macOS

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

2.6.1.Install python-oracledb

Use Python’spip packageto install python-oracledb from Python’s package repositoryPyPI:

python-mpipinstalloracledb--upgrade

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

python-mpipinstalloracledb--upgrade--user

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

python-mpipinstalloracledb--upgrade--user--proxy=http://proxy.example.com:80

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

/usr/bin/python3-mpipinstalloracledb--upgrade--user

2.6.2.Optionally Install Oracle Client

By default, python-oracledb runs in a Thin mode which connects directly toOracle Database so no further installation steps are required. However, to useadditional features available inThick mode you needOracle Client libraries installed.

You can get the libraries from either the Oracle Instant ClientBasic orBasic Light package. The steps below show installingBasic.

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/Downloadscurl-Ohttps://download.oracle.com/otn_software/mac/instantclient/233023/instantclient-basic-macos.arm64-23.3.0.23.09.dmghdiutilmountinstantclient-basic-macos.arm64-23.3.0.23.09.dmg/Volumes/instantclient-basic-macos.arm64-23.3.0.23.09/install_ic.shhdiutilunmount/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 atthe same time.

The Instant Client directory will be like$HOME/Downloads/instantclient_23_3. Applications may not have access totheDownloads directory, so you should move Instant Client somewhereconvenient.

2.6.2.2.Instant Client Manual Installation on macOS ARM64

  • Download the latest Instant ClientBasic ARM64 package DMG fromOracle.

  • Using Finder, double-click the DMG to mount it.

  • Open a terminal window and run the install script in the mounted package,for example if you downloaded version 23.3:

    /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09/install_ic.sh

    The Instant Client directory will be like$HOME/Downloads/instantclient_23_3. Applications may not have access totheDownloads directory, so you should move Instant Client somewhereconvenient.

  • Using Finder, eject the mounted Instant Client package.

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 packagesat 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/Downloadscurl-Ohttps://download.oracle.com/otn_software/mac/instantclient/1916000/instantclient-basic-macos.x64-19.16.0.0.0dbru.dmghdiutilmountinstantclient-basic-macos.x64-19.16.0.0.0dbru.dmg/Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru/install_ic.shhdiutilunmount/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 atthe same time.

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

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

  • Download the latest Instant ClientBasic Intel 64-bit package DMG fromOracle.

  • Using Finder, double-click the DMG to mount it.

  • Open a terminal window and run the install script in the mounted package, for example:

    /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru/install_ic.sh

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

  • Using Finder, eject the mounted Instant Client package.

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 atthe same time.

2.6.3.Configure Oracle Instant Client

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

  1. Calloracledb.init_oracle_client() in your application:

    importoracledboracledb.init_oracle_client(lib_dir="/Users/your_username/Downloads/instantclient_23_3")

  2. If you use optional Oracle configuration files such astnsnames.ora,sqlnet.ora, ororaaccess.xml with Oracle Instant Client, then put thefiles in an accessible directory, for example in/Users/your_username/oracle/your_config_dir. Then use:

    importoracledboracledb.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 variableTNS_ADMIN to that directory name.

    Alternatively, put the files in thenetwork/admin subdirectory of OracleInstant Client, for example in/Users/your_username/Downloads/instantclient_23_3/network/admin. This is thedefault Oracle configuration directory for executables linked with thisInstant 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 repositoryPyPI. Use the file appropriate foryour operating system and python version. Transfer this file to the offlinecomputer and install it with:

python-mpipinstall"<file_name>"

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

Then follow the general python-oracledb platform installation instructions toinstall Oracle Client libraries. This is only necessary if you intend to usepython-oracledbThick mode.

2.8.Installing python-oracledb without the Cryptography Package

If the Python cryptography package is not available, python-oracledb can stillbe installed but can only be used in Thick mode. Trying to use Thin mode willgive the errorDPY-3016:python-oracledbthinmodecannotbeusedbecausethecryptographypackageisnotinstalled.

To use python-oracledb without the cryptography package:

2.9.Installing from Source Code

For platforms that do not have pre-built binaries onPyPI, using the normalpython-mpipinstalloracledb command will download the python-oracledb source bundle,build, and install it.

Alternatively, to create your own package files for installation, you can buildand install python-oracledb eitherlocally from source code,or by using apresupplied GitHub Action which buildspackages 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:

    • You can clone the source code fromGitHub:

      gitclone--recurse-submoduleshttps://github.com/oracle/python-oracledb.git

    • Alternatively, you can manually download asource zipfile from GitHub.

      In this case, you will also need to download anODPI-C source zip file and put theextracted contents inside theodpi subdirectory, for example inpython-oracledb-main/src/oracledb/impl/thick/odpi.

    • Alternatively, clone the source fromopensource.oracle.com, which mirrors GitHub:

      gitclone--recurse-submoduleshttps://opensource.oracle.com/git/oracle/python-oracledb.gitgitcheckoutmain

    • Alternatively, a python-oracledb source package can manually be downloadedfrom PyPI.

      Navigate to thePyPI python-oracledb download files page, download the sourcepackage archive, and extract it.

  3. With the source code available, build a python-oracledb package by running:

    cdpython-oracledb# the name may vary depending on the downloadpython-mpipinstallbuild--upgrade# export PYO_COMPILE_ARGS='-g0'  # optionally set any compilation argumentspython-mbuild

    A python-oracledb wheel package is created in thedist 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-mpipinstalldist/oracledb-3.1.0-cp312-cp312-macosx_14_0_arm64.whl

    The package can also be installed on any computer which has the samearchitecture 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 GitHubinfrastructure to build python-oracledb packages for all architectures andPython versions.

  1. Fork thepython-oracledb repository. Additionally fork theODPI-C repository, keeping thedefault name.

  2. In your python-oracledb fork, go to the Actions tabhttps://github.com/<yourname>/python-oracledb/actions/. If this isyour first time using Actions, confirm enabling them.

  3. In the “All workflows” list on the left-hand side, select the “Buildpython-oracledb packages” entry.

  4. Navigate to the “Run workflow” drop-down, select the branch to build from(for example, “main”), and run the workflow.

  5. Optionally edit the input field list of package targets and remove targetsyou do not want to build. For example, remove “Linux” if you do not wantLinux packages.

  6. When the build has completed, download the “python-oracledb-wheels”artifact, unzip it, and install the one for your architecture and Pythonversion. For example, when using Python 3.12 on macOS, install:

    python-mpipinstalloracledb-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 acentralized configuration provider, you must install the necessary modules for yourpreferred provider as detailed below.

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

For python-oracledb to use anOracle Cloud Infrastructure (OCI) ObjectStorage configuration provider, you must install theOCI package:

python-mpipinstalloci

SeeUsing an OCI Object Storage Centralized Configuration Provider for information on using this configurationprovider with python-oracledb.

2.10.2.Install Modules for the Azure App Centralized Configuration Provider

For python-oracledb to use anAzure App Configuration Provider, you must install theAzure App Configuration,Azure Core, andAzure Identity packages:

python-mpipinstallazure-appconfigurationazure-coreazure-identity

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

python-mpipinstallazure-keyvault-secrets

SeeUsing an Azure App Centralized Configuration Provider for information on using this configurationprovider with python-oracledb.

2.11.Installing Cloud Native Authentication Modules for python-oracledb

To use a python-oracledb Cloud Native Authentication plugin, you must installthe 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 mustinstall thePython SDK for Oracle Cloud Infrastructure package:

python-mpipinstalloci

Review theOCI SDK installation instructionsas needed.

SeeOCI Cloud Native Authentication with the oci_tokens Plugin for more information on using the plugin inpython-oracledb.

2.11.2.Install Modules for the Azure Cloud Native Authentication Plugin

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

python-mpipinstallmsal

Review theMicrosoft MSAL installation instructionsas needed.

SeeAzure Cloud Native Authentication with the azure_tokens Plugin for more information on using the plugin inpython-oracledb.