Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:Python sdist

From ReverseEngineering.wiki
Format
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.gz suffix and exactly one hyphen. Legacy .zip sdists exist: pypa/packaging parse_sdist_filename accepts .tar.gz and .zip and splits name from version at the last dash.
  • One top-level directory {name}-{version}/ containing pyproject.toml, PKG-INFO (metadata version 2.2 or newer) and the source files. From metadata 2.4 the license files named by License-File must 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 tarfile mode r: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

See also

Technique:Install-time code execution in package archives.