Overview

This skill guides you through building Python distributions with uv (wheels and sdists), verifying artifacts, and publishing to PyPI or Test PyPI. It emphasizes a build-verify-publish workflow and relies on dist/ for artifacts.

How This Skill Works

Use uv build to produce distribution artifacts (wheels and sdists) into dist/. You can build a wheel-only package with uv build --no-sources. After verifying the artifact contents, publish to PyPI with uv publish --token $PYPI_TOKEN or to Test PyPI with uv publish --publish-url https://test.pypi.org/legacy/ --token $TEST_PYPI_TOKEN.

When to Use It

• Preparing a new Python package for distribution and release
• Building wheels and sdists for upload to PyPI or Test PyPI
• Verifying dist contents and performing a quick install tests
• First release: validate in Test PyPI before PyPI publication
• Automating or scripting the publish step into CI

Quick Start

1. Step 1: uv build
2. Step 2: uv pip install dist/my_package-1.0.0-py3-none-any.whl
3. Step 3: uv publish --token $PYPI_TOKEN (or use the test URL with $TEST_PYPI_TOKEN for Test PyPI)

Best Practices

• Always run uv build to generate dist/ artifacts before publishing
• Inspect dist/ contents and perform a local install from the wheel to verify packaging correctness
• Use uv publish with a PyPI token; test with Test PyPI first to catch issues
• Publish first to Test PyPI, then to PyPI for a first release
• Avoid publishing before you have validated the wheel contents and dependencies

Example Use Cases

• Build and publish to Test PyPI, verify by installing the wheel, then publish to PyPI
• Build only the wheel with uv build --no-sources, install from dist/, and publish to PyPI
• Publish to Test PyPI using: uv publish --publish-url https://test.pypi.org/legacy/ --token $TEST_PYPI_TOKEN
• Validate a release by installing from dist before clicking publish to PyPI
• Release cadence: uv build -> uv pip install dist/...whl -> uv publish to Test PyPI -> uv publish to PyPI

Frequently Asked Questions