Publishing a Python Package from GitHub to PyPI in 2024
This is my favorite method for publishing a package to PyPI today. It uses the new Trusted Publisher method from PyPI, which makes the whole process very straightforward.
What this does NOT address: writing some python and then setting it up to be a package. Here are a few posts on that:
- https://python-poetry.org/docs/basic-usage/ — how to use poetry to set up your package for you
- https://packaging.python.org/en/latest/tutorials/packaging-projects/ — how to set up a pyproject.toml-based project
- https://drivendata.co/blog/python-packaging-2023 — nitty-gritty about pyproject-toml setup
- https://pythonhosted.org/an_example_pypi_project/setuptools.htm — how to use a setup.py project
This assumes you have a python package set up locally, know how to create a .whl file from it (probably by running python setup.py or python -m build), and want an easy way to turn that into a package on PyPI that others can then install, and then make it easy to update that package as you change your code.
Step 1: Set up your code as a python package, including setup.py/pyproject.toml
In this post I’ll be showing an example of publishing https://github.com/streamlit/gsheets-connection/, which currently uses setup.py for project definition
Make sure that the pypi package name that you’re planning to use matches the name of your package in setup.py / pyproject.toml
Step 2: Create an account on pypi.org, if you don’t already have one
https://pypi.org/account/register/
Step 3: Create a file called .github/workflows/publish.yml and commit it into your repository
name: Upload Python Package to PyPI when a Release is Created
on:
release:
types: [created]
jobs:
pypi-publish:
name: Publish release to PyPI
runs-on: ubuntu-latest
environment:
name: pypi
url: https://pypi.org/p/<PYPI_PACKAGE_NAME>
permissions:
id-token: write
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: "3.x"
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install setuptools wheel
- name: Build package
run: |
python setup.py sdist bdist_wheel # Could also be python -m build
- name: Publish package distributions to PyPI
uses: pypa/gh-action-pypi-publish@release/v1Be sure to change PYPI_PACKAGE_NAME to whatever you want the package to be called on pypi, which needs to be the same as the name value in your pyproject.toml / setup.py
e.g. https://github.com/streamlit/gsheets-connection/pull/12/files
Step 4: Set up a new “Pending Publisher”
https://pypi.org/manage/account/publishing/
Scroll down to “Add a new pending publisher”, and fill in project name, owner, repository name, and publish.yml, then hit “Add”
More details here: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
Step 5: Create a new release
On the right sidebar of github, click on “Releases” and then “Create a new release”
Look at setup.py or pyproject.toml and figure out what the current version number of the package is. For example, 0.0.1
Click on “Choose a tag”, and type in v + the version number (e.g. v0.0.1), and choose “Create a new tag on publish”
Click on “Generate release notes” to automatically generate release notes based on which PRs have been merged since the last release
Click on “publish release”!
Step 6: Make sure the release works
First, check the “Actions” tab in github, and watch the “Upload python package…” action run
If all goes well, you should see the package on pypi! (e.g. https://pypi.org/project/st-gsheets-connection/)
