Course contentsShow
← Python
Lesson 531 of 1,0608. Professional Tooling and PackagingFree lesson

Building Source Distributions and Wheels

Execute standardized build commands to generate sdist and wheel artifacts ready for distribution to the Python Package Index.

In this lesson, you will learn how to transform your project source code into standardized distribution formats ready for publishing to the Python Package Index (PyPI).

The Goal of Distribution

When you share a Python package, you aren't just zipping up your project folder. Instead, you create two distinct artifacts:

  1. Source Distribution (sdist): A compressed archive (usually .tar.gz) containing your raw source code. It is useful for end-users who may need to compile C extensions locally or inspect the code directly.
  2. Wheel (bdist_wheel): A pre-built distribution format (.whl) that acts like a ZIP file containing your code and metadata. It allows for lightning-fast installation because the package is essentially ready to be copied into the user's site-packages directory.

Building with Modern Tooling

Since you are already using uv and a pyproject.toml configuration, building these artifacts is a standardized process. While you could use the legacy build package, uv streamlines this by abstracting the build backend execution.

To generate these files, navigate to your project root in your terminal and run:

uv build

This command invokes the PEP 517 build backend defined in your pyproject.toml. It handles the environment isolation, temporary metadata generation, and artifact creation automatically.

Understanding the Output

Once the command finishes, you will see a new dist/ directory created in your project root. Inside, you will find:

  • your_package-0.1.0.tar.gz (The sdist)
  • your_package-0.1.0-py3-none-any.whl (The wheel)

The wheel’s filename is significant; it includes tags (py3-none-any) that indicate the Python version and platform compatibility. Because your project is structured with pyproject.toml and follows the src-layout, these tools know exactly which files to include (e.g., your source code, your entry points, and your declared static assets) and which to ignore (like your virtual environment or .git folder). These files are now prepared for upload to PyPI using tools like twine.

Key Takeaway: Use uv build to consistently generate both a source distribution for maximum compatibility and a wheel for optimized installation performance.