How do you migrate a legacy setup.py/setup.cfg project to pyproject.toml?

## Three generations in one repository A long-lived project often carries all three packaging generations at once: a `setup.py` that calls `setup(...)`, a `setup.cfg` holding the same information declaratively but in setuptools' own dialect, and (perhaps) a `pyproject.toml` containing only tool configuration. Migration means collapsing that into one standard file, in an order that keeps the project installable at every step. ## Step 1 — declare the build system Before touching metadata, add the table that says who builds the project: ```toml [build-system] requires = ["setuptools>=77"] build-backend = "setuptools.build_meta" ``` This alone is a real improvement: without it a frontend falls back to `setuptools.build_meta:__legacy__` with an implicit, unbounded setuptools requirement, so your build silently tracks whatever version resolves. Staying on setuptools during the migration is deliberate — change one thing at a time. Switching to a lighter backend such as `hatchling.build`, `flit_core.buildapi` or `poetry.core.masonry.api` is a separate, later decision, worth taking for a pure-Python project with simple file inclusion and worth declining while you still need setuptools' handling of compiled extensions or unusual layouts. ## Step 2 — translate the metadata The `setup.cfg` sections map onto `[project]` with a few renames worth memorising: | legacy | standard | | --- | --- | | `[metadata] name`, `version`, `description` | `[project] name`, `version`, `description` | | `[metadata] long_description` / `long_description_content_type` | `[project] readme` | | `[metadata] classifiers` (newline list) | `[project] classifiers` (TOML array) | | `[metadata] url`, `project_urls` | `[project] urls` | | `[options] install_requires` | `[project] dependencies` | | `[options] python_requires` | `[project] requires-python` | | `[options] packages`, `package_dir` | `[tool.setuptools.packages.find]` | Two shape changes catch people out. Legacy fields are newline-separated strings; the standard fields are TOML arrays, so every entry becomes a quoted list element. And authorship moves from flat `author`/`author_email` keys to an array of tables: `authors = [{ name = "…", email = "…" }]`. Also re-check the licence declaration while you are there: modern backends want an SPDX expression string plus a `license-files` glob rather than the old licence classifier convention, and a stale classifier is an easy thing to leave behind. ## Step 3 — decide the fate of setup.py Delete it if it does nothing but call `setup()` with arguments you have just moved. Keep a minimal one only where you need *code* at build time — most commonly to declare compiled extension modules, which have no declarative form. A surviving `setup.py` sits alongside `pyproject.toml`, contains only what must be imperative, and must never import the package it is building: under build isolation that package is not installed, so an import for the sake of reading a version constant fails immediately. Separately, stop *invoking* `setup.py`. `python setup.py sdist`, `bdist_wheel` and especially `install` are deprecated entry points into the build; drive the standard hooks through a frontend instead (`python -m build` to produce artifacts, `pip install .` to install). The file may survive as configuration; running it as a command should not. ## Step 4 — verify the artifact, not the diff Building successfully proves very little. Build the wheel and sdist, install into a clean environment, and read the metadata back: ```python import importlib.metadata as md meta = md.metadata("sensor-collector") print(meta["Name"], meta["Version"], meta.get("Requires-Python")) print(meta.get_all("Requires-Dist")) ``` Compare that against the same output from an artifact built before the change. Typical regressions this catches: a dependency lost because a newline list was translated by hand, a missing `requires-python` floor that now lets the package install on an interpreter it cannot run on, and non-code files that stopped being included because the old inclusion rules lived in the tooling you replaced. Check that `pip install -e .` still works too — editable installs now go through the standard editable hook rather than `setup.py develop`, which is what makes them possible at all for a project with no `setup.py`. ## Sequencing on a live project Do it in separate commits: build-system table first, then metadata translation, then removal of the legacy files. Each step is independently revertible, and each one can be checked by building and diffing the resulting metadata. On a project that publishes regularly, land the migration immediately after a release, not immediately before one, so the first artifact produced by the new configuration has a full cycle of use before anyone depends on it.