# 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](https://pydevtools.com/handbook/explanation/what-is-a-python-package.md). It is one of two standard distribution formats on [PyPI](https://pydevtools.com/handbook/explanation/what-is-pypi.md), the other being [wheel](https://pydevtools.com/handbook/reference/wheel.md).

## 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](https://pydevtools.com/handbook/reference/pyproject.toml.md) specifying the [build backend](https://pydevtools.com/handbook/explanation/what-is-a-build-backend.md)
- Any non-Python files the build backend includes (C extensions, data files, templates)

The format is defined by the [source distribution specification](https://packaging.python.org/en/latest/specifications/source-distribution-format/), which standardized the layout so that any compliant [build frontend](https://pydevtools.com/handbook/explanation/what-is-a-build-frontend.md) 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](https://pydevtools.com/handbook/reference/pip.md) or [uv](https://pydevtools.com/handbook/reference/uv.md) 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

| | sdist | [Wheel](https://pydevtools.com/handbook/reference/wheel.md) |
|---|---|---|
| **Format** | Compressed tarball (`.tar.gz`) | ZIP archive (`.whl`) |
| **Contents** | Source code and build instructions | Pre-built code and metadata |
| **Install speed** | Slower (must build first) | Fast (copy files into place) |
| **Compiler required** | Yes, for packages with C extensions | No |
| **Platform-specific** | No (builds on target) | Yes (tagged per platform) |

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](https://pydevtools.com/handbook/explanation/what-is-a-build-frontend.md) reads the `[build-system]` table in [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md) and delegates to the configured [build backend](https://pydevtools.com/handbook/explanation/what-is-a-build-backend.md):

```bash
# 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.

> [!NOTE]
> Some packages publish only wheels (no sdist). Others publish only an sdist when compiled extensions make cross-platform wheel building impractical without CI infrastructure like [cibuildwheel](https://cibuildwheel.pypa.io/).

## Learn More

- [Source distribution format specification](https://packaging.python.org/en/latest/specifications/source-distribution-format/)
- [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
- [PEP 625 -- File name of a source distribution](https://peps.python.org/pep-0625/)