Publishing Your First Python Package to PyPI

This tutorial guides you through publishing a Python package to the Python Package Index (PyPI) using uv. You’ll learn the essential steps of building and uploading a package that others can install with pip or uv.

Since this is your first package, we’ll start by uploading to TestPyPI, a “separate instance of the Python Package Index that allows you to try distribution tools and processes without affecting the real index.”

Prerequisites

• uv installed (installation guide)
• A TestPyPI account (register here)
• A Python project ready for distribution

Setting Up Your Project

Create a new project with a name that is not currently taken on Test PyPI. You might try something like your name followed by a random number, e.g. timhopper2456543.

$ uv init <PACKAGE_NAME>
$ cd <PACKAGE_NAME>

Building Distributions

Build your package distributions:

$ uv build

This creates two files in the dist/ directory:

• A wheel file (.whl) - Built distribution
• A source distribution (.tar.gz)

Creating a PyPI API Token

1. Log into PyPI
2. Go to Account Settings → API tokens
3. Create a token with “Entire Account” scope
4. Save the token securely - you won’t see it again

Publishing to TestPyPI

Use your saved token to publish:

$ uv publish --token pypi-xxxx-xxxx-xxxx-xxxx --publish-url https://test.pypi.org/legacy/

Verifying Installation

Test that your package installs correctly:

$ uv run --with <PACKAGE_NAME> --no-project -- python -c "import <PACKAGE_NAME>"

Publish to PyPI

When you’re ready to publish to PyPI, you will remove the --publish_url from the publish command and use a token created at pypi.org.

Learn More:

• PyPI Publishing Guide
• uv Publishing Documentation
• Python Package Metadata Specification
• Publishing package distribution releases using GitHub Actions CI/CD workflows