How to Upload a Package to PyPI

This guide explains how to upload a Python package to PyPI using pyproject.toml, build, and twine.

Prepare Your Project Structure

A typical Python package structure looks like this:

my-package/               # Project root (hyphens for PyPI name)
├── my_package/           # Python importable package (underscores)
│   ├── __init__.py       # Required to make it a package
│   └── module.py         # Your module code
├── pyproject.toml        # Build configuration
├── README.md             # Project description
└── LICENSE               # License file

Key Notes:

• The PyPI package name (e.g., my-package) uses hyphens.
• The importable Python name (e.g., my_package) uses underscores.
• A single file my_package.py instead of a directory my_package/ containing __init__.py is also OK.

Create a pyproject.toml File

Here's an example pyproject.toml (using setuptools as the build backend):

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"        # PyPI name (hyphens)
version = "0.1.0"
description = "A description of my-package"
readme = "README.md"
requires-python = ">=3"
license = "MIT"
authors = [
  { name="Jane Doe", email="jane.doe@example.com" }
]
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent",
]
dependencies = [
  "numpy",
]

[project.urls]
"Homepage" = "https://github.com/janedoe/my-package"
"Bug Tracker" = "https://github.com/janedoe/my-package/issues"

Install Required Tools

First, install build and twine:

pip install build twine

Build the Package

Run the following command in your project's root directory:

python -m build

This generates .tar.gz and .whl files in the dist/ folder.

Upload to PyPI

Use twine to upload your package. Navigate to the dist/ directory and run:

twine upload dist/*

You'll be prompted for your PyPI API token. Refer to the official PyPI documentation for details.

Verify Publication

After uploading, check PyPI to see if your package is listed: https://pypi.org/

Search for your package name-it may take a few minutes to appear.