Install & Compatibility
Where this runs
tested against v4.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.590s · 43.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.550s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
oracledb
✓ import oracledb
connect
✓ oracledb.connect(...)
This quickstart demonstrates how to establish a connection to an Oracle Database using `oracledb` in its default Thin mode, execute a simple SQL query, and fetch the result. It uses environment variables for credentials to avoid hardcoding sensitive information.
import os
import oracledb
# Database credentials from environment variables for security
USERNAME = os.environ.get('ORACLE_DB_USER', 'your_username')
PASSWORD = os.environ.get('ORACLE_DB_PASSWORD', 'your_password')
CONNECT_STRING = os.environ.get('ORACLE_DB_DSN', 'localhost/orclpdb') # e.g., 'hostname:port/service_name'
try:
# Establish a connection in Thin mode (default)
with oracledb.connect(user=USERNAME, password=PASSWORD, dsn=CONNECT_STRING) as connection:
print(f"Successfully connected to Oracle Database: {connection.version}")
with connection.cursor() as cursor:
# Execute a simple query
cursor.execute("SELECT SYSDATE FROM DUAL")
for row in cursor:
print(f"Current database date: {row[0]}")
except oracledb.Error as e:
error_obj, = e.args
print(f"Error connecting to Oracle Database: {error_obj.message}")
print("Please ensure ORACLE_DB_USER, ORACLE_DB_PASSWORD, and ORACLE_DB_DSN environment variables are set correctly,")
print("or replace the placeholder values in the script.")
Debug
Known issues
breakingoracledb is the renamed successor to cx_Oracle. While the API is largely compatible, all new development should use `oracledb` as `cx_Oracle` is now obsolete and no longer actively developed. The primary change is the import statement and the default 'Thin mode'.fixReplace `import cx_Oracle` with `import oracledb`. Review and update any explicit `cx_Oracle` class instantiations or methods, although most should be a drop-in replacement.
affects: All versions of cx_Oracle (obsolete) and oracledb (since 1.0.0)
gotchaoracledb operates in two modes: 'Thin' (default, pure Python, no client libraries needed) and 'Thick' (requires Oracle Client libraries for extended features). You can only enable 'Thick mode' once per process by calling `oracledb.init_oracle_client()` *before* creating any connections or connection pools. Attempting to call it after connections are established will result in an error.fixUnderstand the differences between Thin and Thick modes. Call `oracledb.init_oracle_client()` at the very beginning of your application's lifecycle if 'Thick mode' functionality is required.
affects: All versions of oracledb (since 1.0.0)
deprecatedThe `oracledb.makedsn()` method is deprecated. Modern code should construct connection strings directly using keyword arguments in `oracledb.connect()` or `oracledb.create_pool()`, or use an Easy Connect string.fixInstead of `dsn = oracledb.makedsn(host, port, service_name)`, use a formatted string directly like `dsn = f'{host}:{port}/{service_name}'` or pass keyword arguments: `oracledb.connect(host=host, port=port, service_name=service_name, ...)` affects: oracledb 3.0.0 and later
gotchaIn 'Thin mode', `oracledb` does not support Oracle Database native network encryption or checksumming. If these are required, 'Thick mode' must be used, or TLS encryption can be enabled as an alternative.fixFor native network encryption/checksumming, enable 'Thick mode' by installing Oracle Client libraries and calling `oracledb.init_oracle_client()`. Alternatively, configure TLS for secure connections in Thin mode.
affects: All versions of oracledb
gotchaWhen connecting to an Oracle Autonomous Database (ADB) in 'Thin mode' using a wallet, the `wallet_password` parameter in the connection string or `oracledb.connect()` is *not* your database user password. It is the password used to encrypt the ADB wallet itself, set when downloading the wallet from the Oracle Cloud Console.fixEnsure you are using the correct wallet password, distinct from your database user's password, when configuring ADB connections in Thin mode.
affects: All versions of oracledb when connecting to ADB in Thin mode
breakingThe library failed to connect with `DPY-6005: cannot connect to database` and `Connection refused`. This error typically indicates that the specified database host or port is incorrect, the Oracle Database server or its listener is not running, or a firewall is blocking the connection.fixVerify that the database host, port, and service name (or SID) in your connection string are correct. Ensure the Oracle Database server and its listener are running and are accessible from the client machine. Check any relevant firewall rules between the client and the database server.
affects: All versions of oracledb
gotchaInstalling `oracledb` from source (e.g., when a pre-built wheel is unavailable for your Python version and platform) requires a C compiler (like `gcc`) and Python development headers. Without these, the build process for its C extensions will fail.fixEnsure that build tools, including a C compiler (e.g., `build-base` package on Alpine Linux, or `build-essential` on Debian/Ubuntu) and Python development headers (e.g., `python3-dev` on Alpine for Python 3.x or `python3-dev` on Debian/Ubuntu), are installed in your environment before attempting to install `oracledb`.
affects: All versions of oracledb when installing from source without a pre-built wheel
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'oracledb'
The 'oracledb' package is either not installed in the active Python environment or the Python interpreter being used cannot find it. This often happens in virtual environments or when multiple Python installations exist.
fixEnsure you have the 'oracledb' library installed in your current Python environment by running: `python -m pip install oracledb`. If using an IDE, confirm it's configured to use the correct Python interpreter where 'oracledb' is installed.
DPI-1047: Oracle Client library cannot be loaded
This error occurs when `oracledb` is attempting to use its 'Thick mode' (requiring Oracle Client libraries), but it cannot find the necessary Oracle Client libraries or they are incompatible (e.g., incorrect version, 32-bit vs. 64-bit mismatch, or missing environment variables/paths).
fixIf 'Thin mode' (default, no client libraries) meets your needs, remove any `oracledb.init_oracle_client()` calls. If 'Thick mode' is required: 1. Install the appropriate Oracle Instant Client libraries (matching your Python's bitness). 2. For Windows/macOS, pass the `lib_dir` parameter to `oracledb.init_oracle_client()` pointing to the Instant Client directory. 3. For Linux, ensure the Instant Client libraries are in the system's library search path (e.g., `LD_LIBRARY_PATH` environment variable set before Python starts, or configured via `ldconfig`). Never set `ORACLE_HOME` with Instant Client.
ORA-12154: TNS:could not resolve the connect identifier specified
The Oracle client cannot resolve the connection string or service name provided, usually due to an incorrect or missing entry in the `tnsnames.ora` file, an incorrectly configured `sqlnet.ora`, or an unreachable Oracle Listener.
fixVerify the connection string for typos and ensure the service name is correctly defined in your `tnsnames.ora` file. Confirm that `tnsnames.ora` is accessible and in the expected location (or that the `TNS_ADMIN` environment variable points to its directory). Check that the Oracle Listener is running on the database server.
DPY-6005: cannot connect to database. Connection failed with "[Errno 61] Connection refused"
This `oracledb` Thin mode error indicates a network problem where the client application was unable to establish a connection with the database server. This commonly means the database listener is not running, the hostname or port is incorrect, or a firewall is blocking the connection.
fixVerify that the Oracle Database listener is running on the specified host and port. Check network connectivity between your client and the database server. Ensure no firewalls (client or server side) are blocking the connection on the database port (default 1521). Double-check the hostname and port in your connection string.
DPY-3010: connections to this database server version are not supported by python-oracledb in thin mode.
This specific error occurs when `oracledb` in Thin mode attempts to connect to an older Oracle Database version (specifically 11.2 or earlier), which is not supported by Thin mode.
fixTo connect to Oracle Database 11.2 or earlier, enable `oracledb` Thick mode by installing Oracle Client libraries and calling `oracledb.init_oracle_client()` in your code. Alternatively, upgrade your Oracle Database to version 12.1 or later to use Thin mode.
Upgrade
Version history
4.0.2latest on PyPI · released Jul 14, 2026
Audit
Dependencies
cryptographyrequiredAutomatically installed for security features.
Oracle Client libraries (Instant Client)optionalRequired for 'Thick mode' to enable advanced features like connection pooling (DRCP), Oracle Advanced Queuing (AQ) in thick mode, and native network encryption. Not needed for default 'Thin mode'.