Format:Python sdist
| Magic | 1F 8B (gzip) around a tar; .tar.gz suffix |
|---|---|
| Extensions | .tar.gz, legacy .zip |
| On this wiki | Facts · Code · Notes · Topics |
Python source distribution (sdist): a .tar.gz named name-version.tar.gz with a single top-level name-version/ directory holding pyproject.toml, PKG-INFO (core metadata 2.2 or later) and the sources; installing it runs a build backend, so it executes package code at install time.
An sdist is the source archive of a Python project as uploaded to PyPI. The current standard form is identified by a pyproject.toml in the archive; the older distutils/setuptools form (made by setup.py sdist) is not standardised except that a PKG-INFO with metadata 2.2 or later must follow the metadata rules.
Layout
- File name
{name}-{version}.tar.gz(PEP 625), name normalised like wheels, version canonical. Tools may recognise an sdist by the.tar.gzsuffix and exactly one hyphen. Legacy.zipsdists exist: pypa/packagingparse_sdist_filenameaccepts.tar.gzand.zipand splits name from version at the last dash. - One top-level directory
{name}-{version}/containingpyproject.toml,PKG-INFO(metadata version 2.2 or newer) and the source files. From metadata 2.4 the license files named byLicense-Filemust be present. Nothing else is required, so build backends put their own files inside. - The tarball must be POSIX.1-2001 pax with UTF-8 names and readable by Python's
tarfilemoder:gz.
Unpacking safely
Tools must extract with tarfile.data_filter or follow the spec's rules: never write outside the destination, no links pointing outside it, no device files, drop leading slashes, clear setuid/setgid/sticky bits.
Where code runs
Pip builds an sdist before installing: it calls the PEP 517 backend named in pyproject.toml ([build-system] build-backend, with requires installed into an isolated environment), or a legacy setup.py path when none is given. setup.py, the backend and any build-time dependency therefore execute during install (Unverified: the exact fallback rules of pip for archives without pyproject.toml; read pypa/pip src/pip/_internal/operations/build/). A wheel for the same release, when published, avoids this: see Format:Python wheel.
Code & repositories
- https://github.com/pypa/packaging @
ef837aad3127167671eb37b9f6bd8a94ec7ce26e· license: Apache-2.0 OR BSD-2-Clause (declared by the contributor; GitHub's detector did not recognize LICENSE)
PyPA packaging library: wheel and sdist file name parsing in utils.py.
Tested on: source read, not run · checked 2026-10-19; last activity 2026-10-13