Abstract

This PEP defines a specification how licenses are documented in the Python projects.

To achieve that, it:

• Adopts the SPDX license expression syntax as a means of expressing the license for a Python project.
• Defines how to include license files within the projects, source and built distributions.
• Specifies the necessary changes to Core Metadata and the corresponding Pyproject Metadata keys
• Describes the necessary changes to the source distribution (sdist), built distribution (wheel) and installed project standards.

This will make license declaration simpler and less ambiguous for package authors to create, end users to understand, and tools to programmatically process.

The changes will update the Core Metadata specification to version 2.4.

Goals

This PEP’s scope is limited to covering new mechanisms for documenting the license of a distribution package, specifically defining:

• A means of specifying a SPDX license expression.
• A method of including license texts in distribution packages and installed Projects.

The changes that this PEP requires have been designed to minimize impact and maximize backward compatibility.

Non-Goals

This PEP doesn’t recommend any particular license to be chosen by any particular package author.

If projects decide not to use the new fields, no additional restrictions are imposed by this PEP when uploading to PyPI.

This PEP also is not about license documentation for individual files, though this is a surveyed topic in an appendix, nor does it intend to cover cases where the source distribution and binary distribution packages don’t have the same licenses.

Motivation

Software must be licensed in order for anyone other than its creator to download, use, share and modify it. Today, there are multiple fields where licenses are documented in Core Metadata, and there are limitations to what can be expressed in each of them. This often leads to confusion both for package authors and end users, including distribution re-packagers.

This has triggered a number of license-related discussions and issues, including on outdated and ambiguous PyPI classifiers, license interoperability with other ecosystems, too many confusing license metadata options, limited support for license files in the Wheel project, and the lack of precise license metadata.

As a result, on average, Python packages tend to have more ambiguous and missing license information than other common ecosystems. This is supported by the statistics page of the ClearlyDefined project, an Open Source Initiative effort to help improve licensing clarity of other FOSS projects, covering all packages from PyPI, Maven, npm and Rubygems.

The current license classifiers could be extended to include the full range of the SPDX identifiers while deprecating the ambiguous classifiers (such as License :: OSI Approved :: BSD License).

However, there are multiple arguments against such an approach:

• It requires a great effort to duplicate the SPDX license list and keep it in sync.
• It is a hard break in backward compatibility, forcing package authors to update to new classifiers immediately when PyPI deprecates the old ones.
• It only covers packages under a single license; it doesn’t address projects that vendor dependencies (e.g. Setuptools), offer a choice of licenses (e.g. Packaging) or were relicensed, adapt code from other projects or contain fonts, images, examples, binaries or other assets under other licenses.
• It requires both authors and tools understand and implement the PyPI-specific classifier system.
• It does not provide as clear an indicator that a package has adopted the new system, and should be treated accordingly.

Rationale

A survey was conducted to map the existing license metadata definitions in the Python ecosystem and a variety of other packaging systems, Linux distributions, language ecosystems and applications.

The takeaways from the survey have guided the recommendations of this PEP:

• SPDX and SPDX-like syntaxes are the most popular license expressions in many modern package systems.
• Most Free and Open Source Software licenses require package authors to include their full text in a Distribution Package.

Therefore, this PEP introduces two new Core Metadata fields:

• License-Expression that provides an unambiguous way to express the license of a package using SPDX license expressions.
• License-File that offers a standardized way to include the full text of the license(s) with the package when distributed, and allows other tools consuming the Core Metadata to locate a distribution archive’s license files.

Furthermore, this specification builds upon existing practice in the Setuptools and Wheel projects. An up-to-date version of the current draft of this PEP is implemented in the Hatch packaging tool, and an earlier draft of the license files portion is implemented in Setuptools.

Terminology

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Specification

The changes necessary to implement this PEP include:

• additions to Core Metadata, as defined in the specification.
• additions to the author-provided project source metadata, as defined in the specification.
• additions to the source distribution (sdist), built distribution (wheel) and installed project specifications.
• guide for tools handling and converting legacy license metadata to license expressions, to ensure the results are consistent and correct.

Note that the guidance on errors and warnings is for tools’ default behavior; they MAY operate more strictly if users explicitly configure them to do so, such as by a CLI flag or a configuration option.

MIT
BSD-3-Clause
MIT AND (Apache-2.0 OR BSD-2-Clause)
MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)
GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause
LicenseRef-Special-License OR CC0-1.0 OR Unlicense
LicenseRef-Proprietary

Use-it-after-midnight
Apache-2.0 OR 2-BSD-Clause
LicenseRef-License with spaces
LicenseRef-License_with_underscores

[project]
license = "MIT"

[project]
license = "MIT AND (Apache-2.0 OR BSD-2-clause)"

[project]
license = "MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)"

[project]
license = "LicenseRef-Proprietary"

[project]
license-files = ["LICEN[CS]E*", "AUTHORS*"]

[project]
license-files = ["licenses/LICENSE.MIT", "licenses/LICENSE.CC0"]

[project]
license-files = ["LICENSE.txt", "licenses/*"]

[project]
license-files = []

[project]
license-files = ["..\LICENSE.MIT"]

[project]
license-files = ["LICEN{CSE*"]

Backwards Compatibility

Adding a new License-Expression Core Metadata field and a top-level string value for the license key in the pyproject.toml [project] table unambiguously means support for the specification in this PEP. This avoids the risk of new tooling misinterpreting a license expression as a free-form license description or vice versa.

The legacy deprecated Core Metadata License field, license key table subkeys (text and file) in the pyproject.toml [project] table and license classifiers retain backwards compatibility. A removal is left to a future PEP and a new version of the Core Metadata specification.

Specification of the new License-File Core Metadata field and adding the files in the distribution is designed to be largely backwards-compatible with the existing use of that field in many packaging tools. The new license-files key in the [project] table of pyproject.toml will only have an effect once users and tools adopt it.

This PEP specifies that license files should be placed in a dedicated licenses subdir of .dist-info directory. This is new and ensures that wheels following this PEP will have differently-located licenses relative to those produced via the previous installer-specific behavior. This is further supported by a new metadata version.

This also resolves current issues where license files are accidentally replaced if they have the same names in different places, making wheels undistributable without noticing. It also prevents conflicts with other metadata files in the same directory.

The additions will be made to the source distribution (sdist), built distribution (wheel) and installed project specifications. They document behaviors allowed under their current specifications, and gate them behind the new metadata version.

This PEP proposes PyPI implement validation of the new License-Expression and License-File fields, which has no effect on new and existing packages uploaded unless they explicitly opt in to using these new fields and fail to follow the specification correctly. Therefore, this does not have a backward compatibility impact, and guarantees forward compatibility by ensuring all distributions uploaded to PyPI with the new fields conform to the specification.

Security Implications

This PEP has no foreseen security implications: the License-Expression field is a plain string and the License-File fields are file paths. Neither introduces any known new security concerns.

How to Teach This

A majority of packages use a single license which makes the case simple: a single license identifier is a valid license expression.

Users of packaging tools will learn the valid license expression of their package through the messages issued by the tools when they detect invalid ones, or when the deprecated License field or license classifiers are used.

If an invalid License-Expression is used, the users will not be able to publish their package to PyPI and an error message will help them understand they need to use SPDX identifiers. It will be possible to generate a distribution with incorrect license metadata, but not to publish one on PyPI or any other index server that enforces License-Expression validity. For authors using the now-deprecated License field or license classifiers, packaging tools may warn them and inform them of the replacement, License-Expression.

Tools may also help with the conversion and suggest a license expression in many common cases:

• The appendix Appendix: Mapping License Classifiers to SPDX Identifiers provides tool authors with recommendation on how to suggest a license expression produced from legacy classifiers.
• Tools may be able to suggest how to update an existing License value in project source metadata and convert that to a license expression, as also specified in this PEP.

Reference Implementation

Tools will need to support parsing and validating license expressions in the License-Expression field if they decide to implement this part of the specification. It’s up to the tools whether they prefer to implement the validation on their side (e.g. like hatch) or use one of the available Python libraries (e.g. license-expression). This PEP does not mandate using any specific library and leaves it to the tools authors to choose the best implementation for their projects.

Rejected Ideas

Many alternative ideas were proposed and after a careful consideration, rejected. The exhaustive list including the rationale for rejecting can be found in a separate page.

Appendices

A list of auxilliary documents is provided:

• Detailed Licensing Examples,
• User Scenarios,
• License Documentation in Python and Other Projects,
• Mapping License Classifiers to SPDX Identifiers,
• Rejected Ideas in detail.

Acknowledgments

• Alyssa Coghlan
• Kevin P. Fleming
• Pradyun Gedam
• Oleg Grenrus
• Dustin Ingram
• Chris Jerdonek
• Cyril Roelandt
• Luis Villa
• Seth M. Larson
• Ofek Lev

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.