pyproject.tomlsetup.py based project?The current standard source distribution format is identified by thepresence of apyproject.toml file in the distribution archive. The layoutof such a distribution was originally specified inPEP 517 and is formallydocumented here.
There is also the legacy source distribution format, implicitly defined by thebehaviour ofdistutils module in the standard library, when executingsetup.py sdist. This document does not attempt to standardise thisformat, except to note that if a legacy source distribution contains aPKG-INFO file using metadata version 2.2 or later, then it MUST followthe rules applicable to source distributions defined in the metadataspecification.
Source distributions are also known assdists for short.
Asource tree is a collection of files and directories – like a versioncontrol system checkout – which contains apyproject.toml file thatcan be used to build a source distribution from the contained files anddirectories.PEP 517 andPEP 518 specify what is required to meet thedefinition of whatpyproject.toml must contain for something to bedeemed a source tree.
The file name of a sdist was standardised inPEP 625. The file name must be inthe form{name}-{version}.tar.gz, where{name} is normalised according tothe same rules as for binary distributions (seeBinary distribution format),and{version} is the canonicalized form of the project version (seeVersion specifiers).
The name and version components of the filename MUST match the values storedin the metadata contained in the file.
Code that produces a source distribution file MUST give the file a name that matchesthis specification. This includes thebuild_sdist hook of abuild backend.
Code that processes source distribution files MAY recognise source distribution filesby the.tar.gz suffix and the presence of preciselyone hyphen in the filename.Code that does this may then use the distribution name and version from the filenamewithout further verification.
A.tar.gz source distribution (sdist) contains a single top-level directorycalled{name}-{version} (e.g.foo-1.0), containing the source files ofthe package. The name and version MUST match the metadata stored in the file.This directory must also contain apyproject.toml in the format defined inpyproject.toml specification, and aPKG-INFO file containingmetadata in the format described in theCore metadata specifications specification. Themetadata MUST conform to at least version 2.2 of the metadata specification.
If the metadata version is 2.4 or greater, the source distribution MUST containany license files specified by theLicense-File field in thePKG-INFOat their respective paths relative to the root directory of the sdist(containing thepyproject.toml and thePKG-INFO metadata).
No other content of a sdist is required or defined. Build systems can storewhatever information they need in the sdist to build the project.
The tarball should use the modern POSIX.1-2001 pax tar format, which specifiesUTF-8 based file names. In particular, source distribution files must be readableusing the standard library tarfile module with the open flag ‘r:gz’.
Because extracting tar files as-is is dangerous, and the results areplatform-specific, archive features of source distributions are limited.
When extracting a source distribution, tools MUST either usetarfile.data_filter() (e.g.TarFile.extractall(...,filter='data')), ORfollow theUnpacking without the data filter section below.
As an exception, on Python interpreters withouthasattr(tarfile,'data_filter')(PEP 706), tools that normally use that filter (directly on indirectly)MAY warn the user and ignore this specification.The trade-off between usability (e.g. fully trusting the archive) andsecurity (e.g. refusing to unpack) is left up to the tool in this case.
Tools that do not use thedata filter directly (e.g. for backwardscompatibility, allowing additional features, or not using Python) MUST followthis section.(At the time of this writing, thedata filter also follows this section,but it may get out of sync in the future.)
The following files are invalid in ansdist archive.Upon encountering such an entry, tools SHOULD notify the user,MUST NOT unpack the entry, and MAY abort with a failure:
Files that would be placed outside the destination directory.
Links (symbolic or hard) pointing outside the destination directory.
Device files (including pipes).
The following are also invalid. Tools MAY treat them as above,but are NOT REQUIRED to do so:
Files with a.. component in the filename or link target.
Links pointing to a file that is not part of the archive.
Tools MAY unpack links (symbolic or hard) as regular files,using content from the archive.
When extractingsdist archives:
Leading slashes in file names MUST be dropped.(This is nowadays standard behaviour fortar unpacking.)
For eachmode (Unix permission) bit, tools MUST either:
use the platform’s default for a new file/directory (respectively),
set the bit according to the archive, or
use the bit fromrw-r--r-- (0o644) for non-executable files orrwxr-xr-x (0o755) for executable files and directories.
Highmode bits (setuid, setgid, sticky) MUST be cleared.
It is RECOMMENDED to preserve the userexecutable bit.
Tool authors are encouraged to consider howhints for furtherverification intarfile documentation apply to their tool.
November 2020: The original version of this specification was approved throughPEP 643.
July 2021: Defined what a source tree is.
September 2022: The filename of a source distribution was standardized throughPEP 625.
August 2023: Source distribution archive features were standardized throughPEP 721.
December 2024: License files inclusion into source distribution was standardizedthroughPEP 639.