How to Publish a Python Package on PyPI

PyPI Trusted Publishing is the modern recommended way to publish packages when supported by your CI provider. This guide covers manual publishing, which is still useful for understanding the publishing process and for situations where Trusted Publishing isn’t an option.

This guide covers the steps for packaging and publishing Python software on PyPI (Python Package Index) using the traditional Python toolchain. The instructions were developed on Linux but should be broadly applicable to other operating systems.

Python Package Index (PyPI) is a repository of software for the Python programming language. It contains over 600k Python packages. PyPI allows package authors to distribute their software by publishing packages. Python users can then easily download or install them with common Python tools.

This guide assumes you have a project hosted in a public repository on GitHub that you would like to publish. Your project must contain a packaging configuration file (pyproject.toml or the older setup.py).

These are the steps to tag, build, and release:

• Update the version number in your packaging configuration file
• Tag a new release and push it to GitHub:

git fetch --tags
git tag  # view tags
git tag <version>
git push origin <version>

(the version tag identifies the commit associated with the release)

• Create a new virtual environment and install the dependencies:

python3 -m venv
source venv/bin/activate
pip install --upgrade build pip twine

• Build the package:

python -m build

(this will build a source distribution (sdist) and binary distribution (wheel) in the dist directory)

• Validate the built distributions:

python -m twine check dist/*

• Generate an API token
• Upload the new packages to PyPI:

python -m twine check dist/*
python -m twine upload --repository pypi dist/*

(enter the API token when prompted)

After upload completes, the new package will be available to install with pip install <package> (or --upgrade).

The content of your readme from pyproject.toml will be viewable in a browser at: https://pypi.org/project/<package>/<version>/.

After publishing a new release, you should bump the version number in your repo to a development version to signify a new version is open for development.

Note: Newer tools offer alternatives to the traditional Python toolchain, simplifying and automating the build, packaging, and publishing process. Reusable workflows are also available on most CI platforms to streamline publishing and improve security.