{"id":1975,"library":"cx-oracle","title":"cx_Oracle","description":"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.","status":"deprecated","version":"8.3.0","language":"en","source_language":"en","source_url":"https://github.com/oracle/python-cx_Oracle","tags":["database","oracle","sql","driver"],"install":[{"cmd":"pip install cx_Oracle","lang":"bash","label":"Install cx_Oracle"}],"dependencies":[{"reason":"cx_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.","package":"Oracle Client libraries","optional":false},{"reason":"On Linux, the `libaio` package may be required for Oracle Instant Client.","package":"libaio (Linux)","optional":true},{"reason":"On recent Linux versions like Oracle Linux 8, the `libnsl` package may be needed when using Oracle Instant Client 19 or later.","package":"libnsl (Oracle Linux 8+)","optional":true}],"imports":[{"note":"The module name uses a capital 'O' for Oracle. Using 'cx_oracle' (lowercase 'o') will result in a `ModuleNotFoundError`.","wrong":"import cx_oracle","symbol":"cx_Oracle","correct":"import cx_Oracle"}],"quickstart":{"code":"import cx_Oracle\nimport os\n\n# Set the path to the Oracle Instant Client libraries\n# This is recommended for programmatically setting the library path since cx_Oracle 8.0\n# On Windows, example: r\"C:\\oracle\\instantclient_19_11\"\n# On Linux/macOS, example: r\"/opt/oracle/instantclient_19_11\"\n# Replace with your actual Instant Client directory or set ORACLE_CLIENT_LIB_DIR env var\noracle_client_lib_dir = os.environ.get('ORACLE_CLIENT_LIB_DIR', '')\nif oracle_client_lib_dir:\n    try:\n        cx_Oracle.init_oracle_client(lib_dir=oracle_client_lib_dir)\n        print(f\"Initialized Oracle Client from: {oracle_client_lib_dir}\")\n    except cx_Oracle.Error as e:\n        print(f\"Warning: Could not initialize Oracle Client from {oracle_client_lib_dir}. Error: {e}\")\n        print(\"Ensure Oracle Client libraries are correctly installed and path is valid.\")\n\n# Connection details (use environment variables for security in production)\nusername = os.environ.get('ORACLE_DB_USER', 'hr')\npassword = os.environ.get('ORACLE_DB_PASSWORD', 'welcome')\n# Example DSN: \"hostname:port/servicename\" or \"localhost:1521/XEPDB1\"\ndsn = os.environ.get('ORACLE_DB_DSN', 'localhost:1521/XEPDB1') \n\ntry:\n    # Establish a connection to the Oracle Database\n    connection = cx_Oracle.connect(username, password, dsn)\n    print(\"Successfully connected to Oracle Database.\")\n\n    # Create a cursor object\n    cursor = connection.cursor()\n\n    # Execute a simple SQL query\n    cursor.execute(\"SELECT SYSDATE FROM DUAL\")\n\n    # Fetch and print the results\n    for row in cursor:\n        print(f\"Current Oracle DB Date: {row[0]}\")\n\n    # Close the cursor and connection\n    cursor.close()\n    connection.close()\n    print(\"Connection closed.\")\n\nexcept cx_Oracle.Error as e:\n    error_obj, = e.args\n    print(f\"Oracle Database Error: Code {error_obj.code} - {error_obj.message}\")\n    print(\"Please check your connection details and Oracle Client setup.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"For new projects, `pip install oracledb` and use `import oracledb`. For existing cx_Oracle applications, refer to the `python-oracledb` migration guide.","message":"cx_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.","severity":"breaking","affected_versions":"All versions, especially for new development."},{"fix":"Ensure your environment uses Python 3.6 or a later supported version.","message":"Starting 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).","severity":"breaking","affected_versions":"8.0 and later"},{"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.","message":"The 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.","severity":"breaking","affected_versions":"8.0 and later"},{"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()`.","message":"cx_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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Since 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.","severity":"gotcha","affected_versions":"8.0 and later"},{"fix":"Ensure that your Python installation and the Oracle Client libraries (e.g., Instant Client) are both either 32-bit or 64-bit.","message":"When 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.","severity":"gotcha","affected_versions":"All versions on Windows"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}