sdist: Python Source Distribution Format

An sdist (source distribution) is a compressed archive containing the source code, metadata, and build instructions for a Python package. It is one of two standard distribution formats on PyPI, the other being wheel.

What an sdist Contains

An sdist is a .tar.gz archive. Its contents include:

• The package’s Python source code
• A PKG-INFO file with package metadata (name, version, author, license, etc.)
• A pyproject.toml specifying the build backend
• Any non-Python files the build backend includes (C extensions, data files, templates)

The format is defined by the source distribution specification, which standardized the layout so that any compliant build frontend can process it.

How Installation Works

Installing from an sdist is a two-phase process. The installer first unpacks the archive and invokes the project’s build backend to produce a wheel. It then installs that wheel. This means an sdist installation runs arbitrary build code, which may require a C compiler, system libraries, or other build-time dependencies that a pre-built wheel would not.

When pip or uv resolves a package, it prefers a wheel over an sdist when a compatible wheel exists. The sdist serves as a fallback for platforms or Python versions where no matching wheel has been published.

sdist vs Wheel

Because sdists contain source code rather than compiled artifacts, a single sdist works on any platform that has the necessary build tools. Wheels trade that flexibility for speed: they are pre-compiled for specific platform and Python version combinations.

Building an sdist

A build frontend reads the [build-system] table in pyproject.toml and delegates to the configured build backend:

# Using uv
uv build --sdist

# Using the build package
python -m build --sdist

The resulting .tar.gz file is placed in the dist/ directory by default.

When sdists Matter

Most packages on PyPI publish both an sdist and one or more wheels. The sdist serves several purposes:

• Platform coverage: users on platforms without a pre-built wheel can still install the package by building from source.
• Auditing and verification: the sdist provides a reviewable source archive, useful for security-conscious environments and Linux distributions that rebuild packages from source.
• Archival: the sdist preserves the full source code as it existed at release time.

Learn More

• Source distribution format specification
• Packaging Python Projects
• PEP 625 – File name of a source distribution