How to Publish a Python Package on PyPI

This is basically for my own reference (because I always forget the steps), but here are instructions for packaging and publishing Python software on PyPI (Python Package Index). These instructions were created using Linux, but should generally be the same for any operating system.

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 I follow to tag, build, and release:

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

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

  (setting a tag with a version number lets users know which commit coressponds 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 Distributioun (wheel) in the dist directory)

• Generate an API token on PyPI (create an account first if needed)
• Upload the new package to PyPI:

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

  (enter the API token when prompted)

Done!

Your package should now be available on PyPI.

---

Note: You can automate this process to make publishing easier. There are Workflows available on GitHub Actions or your CI tool of choice that will accomplish roughly the same thing.