Flit Migration Check: setup.py to flit_core 4

Six setup.py lines from a sample Python package show what a Flit migration really is: install_requires becomes [project] dependencies, extras_require becomes [project.optional-dependencies], a console_scripts entry becomes [project.scripts], data_files becomes [tool.flit.external-data], python_requires becomes requires-python, and license="MIT" becomes an SPDX license string that needs flit_core >=3.11. If you maintain a pure-Python library on PyPI and you are moving from setuptools, Hatch or the old Flit 3 layout to flit_core 4, this is the list you would otherwise write by hand.

Migrate from setuptools to Flit: what changed in August and September 2026

flit_core 4.0 (on PyPI 2026-08-04) no longer reads [tool.flit.metadata]. The Flit release history says it plainly: the old table "is no longer used for project metadata"; use the [project] table, or build with flit_core <4. A package whose [build-system] asks for "flit_core >=3.2" with no upper bound now receives flit_core 4 when pip builds it from the sdist, and the build stops.

flit_core 4.1 (on PyPI 2026-09-16) accepts license expressions with WITH, such as "Apache-2.0 WITH LLVM-exception". That line needs "flit_core >=4.1,<5" in requires. A plain SPDX expression like "MIT" needs flit_core >=3.11, and import-names needs flit_core >=4. The Flit docs also ask every package to pin "<5".

What the checker does

Flit Migration Check is a VS Code extension with a free web version that runs the same engine. Open setup.py, setup.cfg or pyproject.toml and it prints one finding per line: the line number, what the line is, and the flit_core 4 line that replaces it. It has 38 rules, and each one names its source page on flit.pypa.io.

The bundled sample setup.py gives 22 findings on 22 lines (10 warnings, 12 notes, 0 blockers). A finished flit_core 4 pyproject.toml gives 0 findings, which is the point where you delete setup.py.

Three pyproject.toml cases show how the answer changes with the input:

• An old Flit 3 file with [tool.flit.metadata], [tool.flit.scripts] and "flit_core >=3.2": 3 findings. The metadata table, the scripts table, and the missing <5 bound.
• A Hatch file with hatchling, dynamic = ["version", "dependencies"] and [project.entry-points.console_scripts]: 5 findings. Flit fills only version, description, import-names and import-namespaces from dynamic, and console_scripts belongs in [project.scripts].
• A Flit 3.x file pinned "flit_core >=3.2,<4" with license = "Apache-2.0 WITH LLVM-exception": 3 findings. The <4 pin can become <5, and the WITH license needs flit_core >=4.1.

Blockers: when not to use Flit

Flit builds pure Python only: "If your package needs a build step, you won't be able to use Flit". The checker marks ext_modules, Extension(, cythonize( and custom cmdclass as BLOCKER lines. Version from git tags (setuptools_scm, versioneer) is also a blocker: write the version into the package and add dynamic = ["version"].

Before twine upload

PyPI rejects an upload file over 100.0 MiB by default, and it refuses invalid Trove classifiers and a name too close to an existing project. The classifiers rule reminds you that "Private :: Do Not Upload" blocks an accidental upload.

Free and paid

The single-file map is free with no limit. A workspace key turns every setup.py, setup.cfg and pyproject.toml in the workspace into one dated migration plan. A team key adds an exposure report across projects and a CI gate that fails a build adding new setuptools-only use.