[Docs] Need migration guide for license expression (PEP 639) about TOML-table-based `project.license` deprecation if v77 unavailable

[XuehaiPan]

Summary

TL;DR: TOML-table-based project.license is deprecated in the newest setuptools. But the highest supported setuptools on Python 3.8 only supports TOML-table-based project.license.

---

setuptools v77.0.0 adds license expression (PEP 639) support in:

• Implement PEP 639 #4829
• Add initial support for license expression (PEP 639) #4706

cc @abravalheri @cdce8p

For pyproject.toml with license = { text = "expression" }:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "xxx"
description = "XXX"
readme = "README.md"
requires-python = ">= 3.8"
license = { text = "Apache-2.0" }

It will emit a warning during installation:

  /.../site-packages/setuptools/config/_apply_pyprojecttoml.py:82: SetuptoolsDeprecationWarning: `project.license` as a TOML table is deprecated
  !!

          ********************************************************************************
          Please use a simple string containing a SPDX expression for `project.license`. You can also use `project.license-files`.

          By 2026-Feb-18, you need to update your project and remove deprecated calls
          or your builds will no longer be supported.

          See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for details.
          ********************************************************************************

  !!

However, setuptools v77.0.0 does not support Python 3.8. The maximum supported version of Python 3.8 is v75.3.2 (v75.4.0 removed Python 3.8 support).

If developers change project.license = "Apache-2.0" as the warning suggested (emitted on a Python >=3.9 environment).

  [project]
  requires-python = ">= 3.8"
- license = { text = "Apache-2.0" }
+ license = "Apache-2.0"

The build will break on Python 3.8 due to the lack of PEP-639-supported setuptools (maximum is v75.3.2).

Processing /.../xxx
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  error: subprocess-exited-with-error
  
  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [87 lines of output]
      configuration error: `project.license` must be valid exactly by one definition (2 matches found):
      
          - keys:
              'file': {type: string}
            required: ['file']
          - keys:
              'text': {type: string}
            required: ['text']
      
      DESCRIPTION:
          `Project license <https://peps.python.org/pep-0621/#license>`_.
      
      GIVEN VALUE:
          "Apache-2.0"
      
      OFFENDING RULE: 'oneOf'
      
      DEFINITION:
          {
              "oneOf": [
                  {
                      "properties": {
                          "file": {
                              "type": "string",
                              "$$description": [
                                  "Relative path to the file (UTF-8) which contains the license for the",
                                  "project."
                              ]
                          }
                      },
                      "required": [
                          "file"
                      ]
                  },
                  {
                      "properties": {
                          "text": {
                              "type": "string",
                              "$$description": [
                                  "The license of the project whose meaning is that of the",
                                  "`License field from the core metadata",
                                  "<https://packaging.python.org/specifications/core-metadata/#license>`_."
                              ]
                          }
                      },
                      "required": [
                          "text"
                      ]
                  }
              ]
          }

OS / Environment

Not related.

Additional Information

pyproject.toml is a static configuration file. It is impossible for packages that can support multiple Python versions (including EOLs) and also do not emit warnings during building. The warning can suggest developers use setup.py but I don't think it is encouraged since they are already using pyproject.toml.

I'd suggest to do not deprecate TOML-table-based project.license with only a text key. Make the following equivalent:

[project]
license = { text = "SPDX expression" }

[project]
license = "SPDX expression"

Code of Conduct

• I agree to follow the PSF Code of Conduct

[abravalheri]

Please note that it is not in the scope of this project to support use cases involving discontinued Python versions.

Python 3.8 reached EoL in 2024, so use cases involving 3.8, are no longer supported by setuptools dev team.

If you wish to use the same codebase to support 3.8 and the following Python versions, I suppose you have a couple of options:

• Use the same (old) version of setuptools across the board and only do the changes when you can stop publishing your package for 3.8
• Use dynamic and solve the license specification in setup.py
• Live with the deprecated warning and plan discontinuing your package for 3.8 before the deprecation due date.
• Remove license expressions from the configuration files and instead rely on the automatic license file inclusion for the well-known license file paths (e.g., LICENSE at the root of the project). You would still be distributing license info in the form of license files (which at the end of the day is what counts... SPDX indexes are at the best an approximate proxy for the license file, re-distributors would still have to read the file themselves).

These suggestions are untested. Please make sure to verify and test before adopting.

[XuehaiPan]

Note this issue does not only exist for Python 3.8 but also all existing Python packages using setuptools. The string-based project.license is not backward-compatible (see the error in #4903 (comment)). Developers need to pin build-system.requires if they want to migrate to PEP 639:

[build-system]
requires = ["setuptools >= 77"]
build-backend = "setuptools.build_meta"

[project]
license = "SPDX expression"

However, this ideal setting will not work in the real world. For example, there are many use cases to use pip install --no-build-isolation due to limited internet connection (on a server) or build-system.requires contains big dependency (e.g., torch). The installer will not upgrade setuptools to the PEP 639 supported version (>= 77). A PEP-639-migrated package will break on the user side. Developers have to revert the migration.

Due to this limitation, downstream developers will postpone the PEP 639 migration. The old code will exist until the day the compact layer for table-based project.license is removed and breaks developers' CI.

[abravalheri]

If users want to make sure a version of setuptools that supports a certain feature is being picked up by the build frontend, it does make sense to use a >= for the version specification.

If the environment cannot download the version of the build requirements on the spot, then it needs to be pre-prepared beforehand.

These are normal activities when working on builds, not specific to this release. So in a sense, there is no need for a special guide for v77. The same arguments can be used for the whole parsing of pyproject.toml or setup.cfg before that. People usually omit the >= part because very often the build frontend will download the latest version of setuptools. If they need builds with special requirements (like lack of internet or opt-out of build isolation), then they need to be more careful and ensure the environment is properly set.

If you would to submit a docs PR with improvements that is very welcome, but other than, the release in question is not different than other features previously released.

[abravalheri]

#4904 documents the version introducing PEP 639, so the information is available in the docs and warnings.

Further PRs for documentation improvements and suggestions are welcome.

[XuehaiPan]

#4904 documents the version introducing PEP 639, so the information is available in the docs and warnings.

Thanks! A user-friendly warning can prompt the developers to add a command to upgrade setuptools in their installation guide:

python3 -m pip install --upgrade pip setuptools
python3 -m pip git+https://github.com/owner/some-package
python3 -m pip another-package

Further PRs for documentation improvements and suggestions are welcome.

I wonder if it is suitable to automatically convert project.license = { text = "SPDX" } to project.license = "SPDX". I can submit a PR to implement this if accepted.

setuptools/setuptools/config/_apply_pyprojecttoml.py

Lines 201 to 224 in 7c859e0

	def _license(dist: Distribution, val: str | dict, root_dir: StrPath | None):
	from setuptools.config import expand
	if isinstance(val, str):
	if getattr(dist.metadata, "license", None):
	SetuptoolsWarning.emit("`license` overwritten by `pyproject.toml`")
	dist.metadata.license = None
	_set_config(dist, "license_expression", _static.Str(val))
	else:
	pypa_guides = "guides/writing-pyproject-toml/#license"
	SetuptoolsDeprecationWarning.emit(
	"`project.license` as a TOML table is deprecated",
	"Please use a simple string containing a SPDX expression for "
	"`project.license`. You can also use `project.license-files`.",
	see_url=f"https://packaging.python.org/en/latest/{pypa_guides}",
	due_date=(2026, 2, 18), # Introduced on 2025-02-18
	)
	if "file" in val:
	# XXX: Is it completely safe to assume static?
	value = expand.read_files([val["file"]], root_dir)
	_set_config(dist, "license", _static.Str(value))
	dist._referenced_files.add(val["file"])
	else:
	_set_config(dist, "license", _static.Str(val["text"]))

def _license(dist: Distribution, val: str | dict, root_dir: StrPath | None):
    from setuptools.config import expand

    if isinstance(val, dict) and set(val) == {'text'} and isinstance(val["text"], str):
        # This is for backward compatibility with the old table-based `license` field.
        # Convert the old table-based `license` to a string (PEP 639) if it only contains `text`
        # and no `file` field.
        # E.g. `license = {text = "MIT"}` to `license = "MIT"`
        from ._validate_pyproject.formats import SPDX

        if SPDX(val['text']):
            val = val['text']

    if isinstance(val, str):
        ...
    else:
        ...

The deprecation warning will be still emitted on:

[project]
license = { text = "non SPDX expression" }

or

[project]
license = { file = "/path/to/file" }

[abravalheri]

A user-friendly warning can prompt the developers to add a command to upgrade setuptools in their installation guide:

Adding this instruction could be confusing for general users.
Most of the users don't need setuptools to be installed. And very often it is good that they don't (e.g. to avoid errors when the build isolation from frontend tools are leaky).
The default behaviour of build tools when the file pyproject.toml file exists is to download the build dependencies on the spot.

People that need to use --no-build-isolation (which is not the default) need to add this information to their own package README, because they require special circumstances to build.

---

I wonder if it is suitable to automatically convert project.license = { text = "SPDX" } to project.license = "SPDX".

The thing is that not all project.license.text are SPDX indices, and also some of them may coincidentally be parseable as an SPDX index but the developer may not want it to be interpreted as such. For example, a project may have project.license.text = "MIT", because the original code itself is MIT, but the project may contain bundled code under GPL: while "MIT" is parseable, the actual SPDX index would be "MIT AND GPL-3.0-or-later".

The reason why we have a warning is that we are prompting the user with a call to action, since it is not trivial and immediate to convert between one and the other. I think the best in the case is to refuse to guess, given that it is a form of legal information.