setuptools SetuptoolsDeprecationWarning treated as error in CI

Recent setuptools emits SetuptoolsDeprecationWarning for legacy patterns such as direct setup.py install, easy_install, or deprecated config keys. On its own a warning is harmless, but a strict CI (warnings as errors, or a future setuptools that hard-removes the feature) turns it into a build failure.

What this error means

The log shows "SetuptoolsDeprecationWarning: ..." about a legacy command or config, and either the build is failed by -W error or a newer setuptools has removed the behavior entirely.

setuptools

SetuptoolsDeprecationWarning: setup.py install is deprecated.
!!  Please avoid running setup.py directly.
    Instead, use pypa/build, pypa/installer or other standards-based tools.

Common causes

Calling setup.py directly

Invoking python setup.py install or bdist_wheel is deprecated. setuptools steers you toward build/pip and warns loudly.

A deprecated config key in setup.cfg

Keys and behaviors removed in newer setuptools trigger the warning, which a hardened CI escalates to an error.

How to fix it

Build with standards-based tools

Replace python setup.py ... with python -m build.
Install the resulting artifact with pip install dist/*.whl.
Remove deprecated config keys flagged in the warning.

Terminal

python -m build
pip install dist/*.whl

Pin setuptools while you migrate

If a deprecated path is removed, pin a setuptools that still supports it to keep CI green until you finish the migration.

pyproject.toml

[build-system]
requires = ["setuptools<81", "wheel"]

How to prevent it

Use python -m build, never setup.py install/bdist_wheel.
Watch deprecation warnings in CI logs before they become hard errors.
Migrate static metadata to pyproject.toml.