Automate PyPi releases with Github Actions


Table of Contents

In this article I will show you how to automate your PyPi package releases with Github actions.

This implementation focuses on auto-versioning releases depending on the tag number using semantic versioning (1.0.0, 1.1.0, etc…)

If you just want to to see the code here is the repository with all the needed files


We want to create a release on PyPi according to the tag number we push on Github

For this guide I am assuming you already know how to set up a project in PyPi and the basics of Github, I’ll leave some useful links if you have no idea of what I am talking about


  1. Generate PyPi API token
  2. Store PyPi API token in your Github repository Secrets
  3. Define your file
  4. Define Github workflow file
  5. Push tags and enjoy

Step by Step

1. Generate PyPi API token

For this you will go to PyPi to create an API token, this is so Github can authenticate against PyPi with your user.

2. Store PyPi API token in your Github repository Secrets

Now that you have your PyPi API token, we need to safely store it so Github can fetch it. For that you will need to go to your repository secrets Repository > Settings > Actions > New Repository Secret In here you will name your secret PYPI_API_TOKEN and then paste your PyPi API token

3. Define your file

Next is to modify your file to dynamically version your releases The important line is the one with VERSION_PLACEHOLDER string. This string will get updated by Github Actions at run time, so you don’t need to update it every time you make a new release. It will get populated with the value you assign to the tag i.e. 1.0.0, 1.1.1, etc..

Sample file
from setuptools import setup, find_packages
import codecs
import os

here = os.path.abspath(os.path.dirname(__file__))

with, ""), encoding="utf-8") as fh:
    long_description = "\\n" +

    author="John Doe",
    description="my amazing package",
    url = "",
    keywords=['pypi', 'cicd', 'python'],
        "Development Status :: 1 - Planning",
        "Intended Audience :: Developers",
        "Programming Language :: Python :: 3",
        "Operating System :: Unix",
        "Operating System :: MacOS :: MacOS X",
        "Operating System :: Microsoft :: Windows"

4. Define Github workflow file

Just copy and paste the file under  repository/.github/workflows/pipy_release.yml
Things you might want to change
– Python version
– Runner (

name: Publish Python 🐍 distributions 📦 to PyPI

     - '*'

    name: Build and publish Python 🐍 distributions 📦 to PyPI
    runs-on: ubuntu-18.04
    - uses: actions/checkout@master
    - name: Set up Python 3.10
      uses: actions/setup-python@v3
        python-version: '3.10'
    - name: Install pypa/setuptools
      run: >-
        python -m
        pip install wheel
    - name: Extract tag name
      id: tag
      run: echo ::set-output name=TAG_NAME::$(echo $GITHUB_REF | cut -d / -f 3)
    - name: Update version in
      run: >-
        sed -i "s/{{VERSION_PLACEHOLDER}}/${{ steps.tag.outputs.TAG_NAME }}/g"
    - name: Build a binary wheel
      run: >-
        python sdist bdist_wheel
    - name: Publish distribution 📦 to PyPI
      uses: pypa/gh-action-pypi-publish@master
        password: ${{ secrets.PYPI_API_TOKEN }}

5. Push your code to your main branch and then create a tag by running

git tag 0.0.1 # or whatever version you want 
git push origin --tags

After this you will see Github actions in action (I couldn’t resist) and if everything is correct, you package will get deployed to PyPi (even if its for the first time)

You will be able to see your Github actions runs at repository > actions

Project containing files explained in the tutorial here

Notify of
Inline Feedbacks
View all comments

Subscribe to our blog

Table of Contents

Would love your thoughts, please comment.x

You like this content?

Subscribe to our blog and stay tuned for all the new pieces of weekly content that we have for you.

Need help with your malware?

Receive a personalized quote in less than 24 hrs.

Or schedule a 30 min discovery call with us

Open chat
Need Help?
Hello 👋
Tap here for a personalized chat with your Solutions Architect.