Introduction

Starting with setuptools 67.3.0, numerous setup.py-only patterns trigger SetuptoolsDeprecationWarning messages during package builds. These warnings appear in CI pipelines, local development, and automated release processes. The warnings signal that setuptools is moving toward PEP 517/518 compliance, which requires build configuration in pyproject.toml rather than imperative setup.py scripts. While warnings do not break builds immediately, they indicate future incompatibility and should be addressed to prevent build failures when setuptools removes legacy support.

Symptoms

During pip install -e . or python -m build, you see warnings like:

/usr/local/lib/python3.11/site-packages/setuptools/config/_apply_pyprojecttoml.py:82: SetuptoolsDeprecationWarning: license` overwritten by pyproject.toml warnings.warn(msg, warning_class)

/usr/local/lib/python3.11/site-packages/setuptools/command/build_py.py:202: SetuptoolsDeprecationWarning: Installing 'my_package.data' as data is deprecated, please list it in package_data. !!

############################ # Please make sure data is listed in package_data in pyproject.toml # ############################ !!

/usr/local/lib/python3.11/dist-packages/setuptools/config/setupcfg.py:294: SetuptoolsDeprecationWarning: !!! Missing build requirements in pyproject.toml.

setuptools will stop enforcing build-system.requires in the future. !! ```

Or more severely:

bash
error in my-package setup command: use_2to3 is invalid.

This occurs when setuptools 58+ removes the use_2to3 option entirely.

Common Causes

  • **Legacy setup.py with setup_requires**: This key was deprecated in favor of PEP 518 build-system.requires
  • **use_2to3 in setup()**: The Python 2 to 3 conversion tool was removed in setuptools 58
  • **Missing pyproject.toml**: Building with only setup.py triggers fallback warnings
  • Conflicting configuration: Having both setup.cfg and pyproject.toml with overlapping settings causes override warnings
  • **python_requires not specified**: Builds silently allow incompatible Python versions
  • **find_packages() with incorrect excludes**: Data files or tests getting bundled into the distribution

Step-by-Step Fix

Step 1: Create a minimal `pyproject.toml`

Replace setup.py with a declarative pyproject.toml:

```toml [build-system] requires = ["setuptools>=68.0", "wheel"] build-backend = "setuptools.build_meta"

[project] name = "my-package" version = "1.2.3" description = "A well-configured Python package" readme = "README.md" license = {text = "MIT"} requires-python = ">=3.9" authors = [ {name = "Your Name", email = "you@example.com"} ] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] dependencies = [ "requests>=2.28.0", "pydantic>=2.0", ]

[project.optional-dependencies] dev = [ "pytest>=7.0", "mypy>=1.0", ]

[project.scripts] my-cli = "my_package.cli:main"

[tool.setuptools.packages.find] where = ["src"] exclude = ["tests*"] ```

Step 2: Move package data configuration

If your setup.py used package_data or include_package_data, move them:

```toml [tool.setuptools.package-data] my_package = ["py.typed", "*.json", "data/*.csv"]

[tool.setuptools] include-package-data = true ```

Step 3: Remove `setup.py` or keep it minimal

If you have custom build logic that cannot be expressed declaratively, keep a minimal setup.py:

```python from setuptools import setup

# Only use this if you have dynamic setup logic that pyproject.toml cannot handle. # Most projects can remove this file entirely. setup() ```

Then run pip install -e . to verify the build works without warnings:

bash
python -m pip install --upgrade setuptools>=68.0
python -m build 2>&1 | grep -i warning
# Should produce no SetuptoolsDeprecationWarning output

Prevention

  • Pin setuptools>=68.0 in your CI environment to catch deprecations early
  • Add python -W error::SetuptoolsDeprecationWarning -m build to CI to fail on warnings
  • Use pip check in CI to detect configuration conflicts
  • Migrate all setup_requires to build-system.requires in pyproject.toml
  • Never use use_2to3 -- drop Python 2 support entirely
  • Run python -m pip install build && python -m build --wheel as part of your PR checks