Registry / database / cx-oracle

cx-oracle

JSON →
library8.3.0pypypi✓ verified 25d ago

cx_Oracle is a Python extension module that enables access to Oracle Database, conforming to the Python Database API v2.0 specification. The current version is 8.3.0, released in November 2021, and introduced official support for Python 3.10. However, it is officially deprecated in favor of `python-oracledb` by Oracle, which is recommended for new projects.

pip install cx_Oracle
INSTALL
IMPORT
SIG · CX-ORACLE
C
cx-oracle
databasepythonv8.3.0
Install
1.9s avg
Import
10ms
Disk
21MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v8.3.0 · 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
musl
glibc
py 3.10
✕ build_error
✓ 1.7s
py 3.11
✕ build_error
✕ build_error
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 2.1s
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cx_Oracle
import cx_Oracle
import cx_oracle
The module name uses a capital 'O' for Oracle. Using 'cx_oracle' (lowercase 'o') will result in a `ModuleNotFoundError`.

This quickstart demonstrates how to establish a connection to an Oracle database, execute a simple query, and fetch results using `cx_Oracle`. It includes `cx_Oracle.init_oracle_client()` for explicit Oracle Client library path configuration and uses environment variables for sensitive connection details.

import cx_Oracle import os # Set the path to the Oracle Instant Client libraries # This is recommended for programmatically setting the library path since cx_Oracle 8.0 # On Windows, example: r"C:\oracle\instantclient_19_11" # On Linux/macOS, example: r"/opt/oracle/instantclient_19_11" # Replace with your actual Instant Client directory or set ORACLE_CLIENT_LIB_DIR env var oracle_client_lib_dir = os.environ.get('ORACLE_CLIENT_LIB_DIR', '') if oracle_client_lib_dir: try: cx_Oracle.init_oracle_client(lib_dir=oracle_client_lib_dir) print(f"Initialized Oracle Client from: {oracle_client_lib_dir}") except cx_Oracle.Error as e: print(f"Warning: Could not initialize Oracle Client from {oracle_client_lib_dir}. Error: {e}") print("Ensure Oracle Client libraries are correctly installed and path is valid.") # Connection details (use environment variables for security in production) username = os.environ.get('ORACLE_DB_USER', 'hr') password = os.environ.get('ORACLE_DB_PASSWORD', 'welcome') # Example DSN: "hostname:port/servicename" or "localhost:1521/XEPDB1" dsn = os.environ.get('ORACLE_DB_DSN', 'localhost:1521/XEPDB1') try: # Establish a connection to the Oracle Database connection = cx_Oracle.connect(username, password, dsn) print("Successfully connected to Oracle Database.") # Create a cursor object cursor = connection.cursor() # Execute a simple SQL query cursor.execute("SELECT SYSDATE FROM DUAL") # Fetch and print the results for row in cursor: print(f"Current Oracle DB Date: {row[0]}") # Close the cursor and connection cursor.close() connection.close() print("Connection closed.") except cx_Oracle.Error as e: error_obj, = e.args print(f"Oracle Database Error: Code {error_obj.code} - {error_obj.message}") print("Please check your connection details and Oracle Client setup.")
Debug
Known issues
breakingcx_Oracle has been officially obsoleted by `python-oracledb`. New projects are strongly encouraged to use `python-oracledb` for better performance, easier installation (thin mode by default, no Oracle Client libraries needed), and continued feature development.
fix
For new projects, `pip install oracledb` and use `import oracledb`. For existing cx_Oracle applications, refer to the `python-oracledb` migration guide.
affects: All versions, especially for new development.
breakingStarting with cx_Oracle 8.0, Python 2.x is no longer supported. cx_Oracle 8.x and later only supports Python 3 (specifically 3.6-3.10 for version 8.3.0).
fix
Ensure your environment uses Python 3.6 or a later supported version.
affects: 8.0 and later
breakingThe default encoding for all character data changed to UTF-8 in cx_Oracle 8.0. While this aligns with Python 3 best practices, applications relying on older default encodings might see unexpected behavior if not explicitly handled.
fix
Explicitly specify `encoding='UTF-8'` in `cx_Oracle.connect()` or `SessionPool()` calls if not already doing so, or if you were relying on a different default. Review character handling in your application.
affects: 8.0 and later
gotchacx_Oracle requires Oracle Client libraries to be installed separately on the system. If these libraries are not found in the system's search path (e.g., `PATH` on Windows, `LD_LIBRARY_PATH` on Linux), you will encounter errors like `DPI-1047: Cannot locate a 64-bit Oracle Client library`.
fix
Download and install Oracle Instant Client for your operating system and ensure its directory is either in your system's `PATH`/`LD_LIBRARY_PATH` or explicitly provided to `cx_Oracle.init_oracle_client()`.
affects: All versions
gotchaSince cx_Oracle 8.0, the recommended and preferred method for locating Oracle Client libraries is to call `cx_Oracle.init_oracle_client()` at the start of your application, passing the path to the client libraries. This is especially important for macOS and is an alternative to setting system environment variables on Windows.
fix
Use `cx_Oracle.init_oracle_client(lib_dir="/path/to/instant/client")` in your Python code before establishing any connections. This avoids potential conflicts with system-wide environment variables.
affects: 8.0 and later
gotchaWhen installing cx_Oracle via pip on Windows, you might encounter issues if Python and the Oracle Client libraries are not both 32-bit or both 64-bit. Mismatched architectures will lead to loading errors.
fix
Ensure that your Python installation and the Oracle Client libraries (e.g., Instant Client) are both either 32-bit or 64-bit.
affects: All versions on Windows
Upgrade
Version history
8.3.0latest on PyPI · released Nov 4, 2021
Audit
Dependencies
Oracle Client librariesrequiredcx_Oracle requires external Oracle Client libraries (e.g., Oracle Instant Client, or a full Oracle Client installation) to connect to an Oracle Database. The architecture (32-bit or 64-bit) of the client libraries must match that of your Python installation.
libaio (Linux)optionalOn Linux, the `libaio` package may be required for Oracle Instant Client.
libnsl (Oracle Linux 8+)optionalOn recent Linux versions like Oracle Linux 8, the `libnsl` package may be needed when using Oracle Instant Client 19 or later.
Agent activity
54 hits · last 30 days
node
50
OpenAI (training)
1
Resources
cx-oracle — pip install cx-oracle · libregistry