cx_Oracle 8.3.0 installation breaks with setuptools 82.0.0 due to pkg_resources removal

[SoniaComp]

Below is the content written in English, following the requested GitHub issue format:

1. What versions are you using?

cx_Oracle version: 8.3.0

setuptools version: 82.0.0 (latest at the time of installation)

(Additional Python/platform information can be provided if needed.)

2. Describe the problem

When installing cx_Oracle 8.3.0, the installation fails due to a compatibility issue with newer versions of setuptools.

Starting from setuptools v82.0.0, pkg_resources is no longer supported (see:
https://github.com/pypa/setuptools/blob/v82.0.0/NEWS.rst#deprecations-and-removals
).

Because of this removal, the installation process raises the following error:

ModuleNotFoundError: No module named 'pkg_resources'

To resolve this issue, we plan to set an upper bound for the setuptools version (i.e., < 82.0.0) to prevent installation failures.

3. Oracle Client libraries

(Not applicable in this case — the issue occurs during package installation before Oracle Client configuration.)

4. PATH / LD_LIBRARY_PATH

(Not applicable — installation fails before runtime.)

5. Oracle environment variables

(Not applicable — installation fails before runtime.)

[anthony-tuininga]

See the comment on #674. Even adjusting pyproject.toml requires a new release due to the requirements imposed by PyPI. No releases are planned, however, so this cannot be implemented. Those intending to build cx_Oracle themselves will need to implement this themselves or ensure that an appropriate setuptools is already in the environment prior to building cx_Oracle -- thereby bypassing the need to install setuptools 82.

[cjbj]

Users of cx_Oracle should be upgrading to its successor python-oracledb.

[theleerise]

You can resolve the installation issue by setting up a clean virtual environment and installing dependencies in a controlled order. The key point is to install cx_Oracle separately without build isolation to avoid compilation problems related to pkg_resources. Here is the exact process:

# Create a fresh virtual environment
python3.14 -m venv venv
source venv/bin/activate

# Prepare build environment
pip install --upgrade pip
pip install "setuptools<82" wheel

# Install cx_Oracle with special flag to avoid build issues
pip install --no-build-isolation cx_Oracle==8.3.0

# Install remaining dependencies
pip install -r requirements.pro.txt

This approach ensures compatibility and prevents common build failures during installation.