Skip to content

Publishing Your First Python Package to PyPI

by Tim Hopper
Packaging uv

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

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. Browse the project’s URL at https://test.pypi.org/project/<PACKAGE_NAME>/ first; if it returns a project page rather than a 404, the name is taken and uv publish will fail later.

$ uv init <PACKAGE_NAME>
Initialized project `<PACKAGE_NAME>` at `/path/to/<PACKAGE_NAME>`
$ cd <PACKAGE_NAME>

Notice the pyproject.toml uv created. It declares the package name, version, and requires-python. TestPyPI uses those fields to register your release.

Building Distributions

Build your package distributions from the project root:

$ uv build
Building source distribution...
running egg_info
... (setuptools build output) ...
Successfully built dist/<PACKAGE_NAME>-0.1.0.tar.gz
Successfully built dist/<PACKAGE_NAME>-0.1.0-py3-none-any.whl

If you see × Failed to build ...does not appear to be a Python project, as neither pyproject.toml nor setup.py are present, you ran uv build from outside the project. Run cd <PACKAGE_NAME> first.

This creates two files in the dist/ directory:

Notice both filenames carry 0.1.0 from pyproject.toml. TestPyPI rejects re-uploads of an existing version, so any future publish will need a version bump in pyproject.toml followed by another uv build.

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/
Publishing 2 files to https://test.pypi.org/legacy/
Uploading <PACKAGE_NAME>-0.1.0-py3-none-any.whl (1.3KiB)
Uploading <PACKAGE_NAME>-0.1.0.tar.gz (930B)

If you see 403 Forbidden, either the token is wrong or another TestPyPI user already owns the project name. Pick a different name, regenerate the project with uv init, and rebuild before retrying. If you see 400 File already exists, you previously uploaded version 0.1.0; bump the version field in pyproject.toml, re-run uv build, and try again.

Verifying Installation

Test that your package installs correctly:

$ uv run --index https://test.pypi.org/simple --with <PACKAGE_NAME> --no-project -- python -c "import <PACKAGE_NAME>"

The command prints nothing on success. python -c "import ..." exits cleanly when the import works, so silence here means the upload landed and the package installs.

Notice the --no-project flag. It tells uv to ignore the local pyproject.toml so the package is fetched from TestPyPI into a fresh environment instead of resolved from your working directory.

If you see No solution found when resolving dependencies or a 404 on the package URL, TestPyPI may not have indexed the upload yet. Wait a minute and try again.

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:

Last updated on
Migrate a conda project to pixiRun your first Python script with uv