Install oracledb in Python

oracledb is the official Python driver for Oracle Database. It replaces the obsolete cx_Oracle driver and supports modern Python versions.

The driver runs in two modes. Thin mode works out of the box. Thick mode adds advanced features through Oracle Client libraries.

This guide shows you how to install the driver, choose the right mode, connect to a database, and fix the most common setup errors.

Prerequisites

You need Python 3.9 to 3.13 for recent versions of python-oracledb. Older versions supported older Python releases, but support has narrowed over time[reference:0].

Check your Python version before installing anything.

python --version
python3 --version

Create a virtual environment to keep the driver isolated. This avoids conflicts with other database packages.

# Create a virtual environment
python -m venv oracle-env

# Activate on Linux or macOS
source oracle-env/bin/activate

# Activate on Windows
oracle-env\Scripts\activate

You also need access to an Oracle Database. The connection string follows the format hostname:port/servicename, such as localhost:1521/orclpdb[reference:1].

Install oracledb with pip

The installation is a single command. The module name is simply oracledb, not python-oracledb.

python -m pip install oracledb --upgrade

The --upgrade flag pulls the latest stable release. This matters because the driver adds features and fixes frequently.

If you are upgrading from cx_Oracle, you can install both packages and use them in the same application during migration. The new driver is the major version successor to cx_Oracle 8.3[reference:2].

On systems where you cannot modify the global Python installation, use the --user flag.

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

If you are behind a corporate proxy, pass the proxy address to pip.

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

Pin the version in your dependency file for reproducible deployments.

pip freeze | grep oracledb >> requirements.txt

Understand Thin Mode vs Thick Mode

Thin mode is the default. It connects directly to Oracle Database and needs no Oracle Client libraries[reference:3].

Thick mode uses Oracle Client libraries for advanced functionality. Both modes support the Python Database API v2.0 specification[reference:4].

Start with Thin mode unless you specifically need a feature that requires Thick mode. Thin mode is simpler and has fewer system dependencies.

All connections in an application use the same mode. You cannot mix Thin and Thick connections in one process[reference:5].

Connect in Thin Mode

A basic connection needs a username, password, and connection string. No extra installation is required beyond the pip package.

import oracledb
import getpass

username = "scott"
dsn = "localhost:1521/orclpdb"

password = getpass.getpass(f"Enter password for {username}@{dsn}: ")

# Connect in the default Thin mode
with oracledb.connect(user=username, password=password, dsn=dsn) as connection:
    with connection.cursor() as cursor:
        for row in cursor.execute("SELECT sysdate FROM dual"):
            print(row)

(datetime.datetime(2026, 10, 19, 14, 32, 11),)

If this prints a datetime value, your Thin mode setup works. The connect() method opens a connection, and the cursor() method creates a cursor for queries.

Enable Thick Mode

Thick mode requires Oracle Client libraries. Install one of the following before calling the initialization function.

Use an Oracle Instant Client Basic or Basic Light package for the simplest setup. You can also use a full Oracle Client installation or an Oracle Database installation on the same machine[reference:6].

Download and unzip the Instant Client package to a directory. Then call init_oracle_client() before creating any connection.

import oracledb

# Point to the unzipped Instant Client directory
oracledb.init_oracle_client(lib_dir="/opt/oracle/instantclient_23_5")

# Now connections use Thick mode
connection = oracledb.connect(
    user="scott",
    password="tiger",
    dsn="localhost:1521/orclpdb",
)
print("Connected in Thick mode.")
connection.close()

Connected in Thick mode.

The init_oracle_client() method must run before any standalone connection or pool is created. If a Thin connection is made first, Thick mode cannot be enabled in that process[reference:7].

On Linux, you can omit the lib_dir argument if the libraries are already in the system library search path, configured with ldconfig. On Windows and macOS, passing the directory is the clearest approach[reference:8].

Verify the Connection

After installation, confirm which mode the driver is using. This prevents confusion when features behave differently.

Call is_thin_mode() to check the active mode.

import oracledb

# In Thin mode (default)
print("Thin mode active:", oracledb.is_thin_mode())

# After enabling Thick mode
# oracledb.init_oracle_client(lib_dir="/path/to/client")
# print("Thin mode active:", oracledb.is_thin_mode())

Thin mode active: True

You can also query the database version to confirm that communication works end to end.

import oracledb

with oracledb.connect(user="scott", password="tiger", dsn="localhost:1521/orclpdb") as conn:
    with conn.cursor() as cursor:
        cursor.execute("SELECT banner FROM v$version WHERE rownum = 1")
        print(cursor.fetchone()[0])

Oracle Database 23ai Enterprise Edition Release 23.0.0.0.0

The fetchone() method returns the first row as a tuple. This query confirms that the driver can read from the database.

Troubleshoot Installation Errors

Most installation problems are caused by old packaging tools or network restrictions. The official troubleshooting guide covers the common cases[reference:9].

Not a supported wheel on this platform

This error appears when pip is outdated. Upgrade pip and retry the installation[reference:10].

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

Network connection error

A proxy or firewall can block PyPI. Set the http_proxy and https_proxy environment variables, or pass the --proxy flag to pip[reference:11].

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

Upgrade succeeded but the old version is still active

An old installation can remain in place after an upgrade. Force a clean reinstall[reference:12].

python -m pip install oracledb --upgrade --force-reinstall

No module named pip

Some operating systems remove the bundled pip module. Use a virtual environment instead, which includes its own pip[reference:13].

DPI-1047: Cannot locate a 64-bit Oracle Client library

This error appears in Thick mode when the driver cannot find the Oracle Client libraries. Check the lib_dir path in init_oracle_client().

On Linux, confirm that the libraries are in the search path or that the directory is correct. In Docker containers, library paths sometimes differ from the host, so verify the mount points[reference:14].

If you do not need Thick mode features, remove the initialization call and use Thin mode instead. It needs no client libraries at all.

Best Practices for a Clean Setup

Start with Thin mode. Add Thick mode only when a specific feature requires Oracle Client libraries.

Pin the driver version in requirements.txt. Oracle Database features and driver behavior can change between releases.

Never hardcode credentials in your source code. Read them from environment variables or a secrets manager.

import os
import oracledb

connection = oracledb.connect(
    user=os.environ["ORACLE_USER"],
    password=os.environ["ORACLE_PASSWORD"],
    dsn=os.environ["ORACLE_DSN"],
)

If your application also uses MySQL, the setup patterns are similar. You can follow a guide to install mysqlclient in Python and compare driver configuration across both databases.

Monitor database connection failures in production. You can install sentry-sdk in Python and capture exceptions from your Oracle queries automatically.

If you run Oracle workloads on Kubernetes, manage Kubernetes pods with Python to automate health checks and restart failed database clients.

Test the connection after every deployment. A quick SELECT 1 FROM dual query catches credential and network issues early.

Keep the driver and Oracle Client library versions compatible. Oracle Client libraries from versions 11.2 through 21c are supported by python-oracledb in Thick mode[reference:15].

Conclusion

Installing oracledb in Python is straightforward. Install the package with pip, and Thin mode works immediately without extra system libraries.

Use Thick mode only when you need advanced Oracle features. Install Oracle Instant Client, then call init_oracle_client() before creating connections.

Fix installation errors by upgrading pip, configuring proxies, or force-reinstalling the package. Check the client library path if Thick mode fails.

With these steps, your Python application connects to Oracle Database reliably in either mode.