How to Upload Python Packages to PyPI in GitHub Actions

name: 'Usage of gh-action-pypi-publish GitHub Action'
environment:
  name: pypi
  url: https://pypi.org/p/<your-pypi-project-name>
permissions:
  id-token: write 
on:
    push:
        branches:
            - main
jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v4
        - name: Publish package distributions to PyPI
          uses: pypa/gh-action-pypi-publish@release/v1

PyPI Publish

The blessed :octocat: GitHub Action, for publishing your 📦 distribution files to PyPI: https://github.com/marketplace/actions/pypi-publish

What is PyPI Publish GitHub Action?​

You can make releasing your Python packages to PyPI easier with the pypi-publish GitHub Action. Below in minimalistic way of using the action. If you want to more verbose guide, please see PyPA guide.

How to Manage Advanced Release Management in GitHub Actions​

Ideally, you want to determine your workflow that’s specific to your project. Use this example to implement advanced release management through GitHub Actions, which would push each commit to your TestPyPI or to your own index server, like devpi.

- name: Publish package to TestPyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
    password: ${{ secrets.TEST_PYPI_API_TOKEN }}
    repository-url: https://test.pypi.org/legacy/

How to Customize the Target Package Directory in GitHub Actions for PyPI​

You can customize here the target directory that your packages are built and saved in—in advance of your upload to PyPI. By default, packages go inside the dist/ directory, but it can be set to a directory of your preference.

- name: Publish package to PyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
    packages-dir: custom-dir/

How to Disable Metadata Verification in GitHub Actions for PyPI​

If you are uploading a release of a Python package to PyPI from GitHub Actions it is strongly recommended that you run twine check to ensure package metadata is in order. Of course, if you don’t need it, you can disable this. This guide shows how to implement target-dir customization and to disable metadata verification.

with:
  verify-metadata: false

How to Tolerate Release Package File Duplicates in GitHub Actions for PyPI​

When publishing releases from multiple sources, you may encounter race conditions that lead to duplicate package files. This guide explains how to handle such situations using the skip-existing setting in GitHub Actions.

with:
  skip-existing: true

How to Debug Twine Upload Failures in GitHub Actions for PyPI​

When uploading packages to PyPI, you might encounter issues that require debugging. This guide explains how to enable verbose logging to help troubleshoot twine upload failures.

with:
  verbose: true

How to Verify File Uploads with Hash Values in GitHub Actions for PyPI​

When uploading packages to PyPI, you might want to verify the integrity of the files by checking their hash values. This guide explains how to enable hash value printing for files to be uploaded using GitHub Actions.

with:
  print-hash: true

How to Specify a Different Username for PyPI Uploads in GitHub Actions​

When publishing to custom registries that do not use API tokens, you may need to specify a custom username and password. This guide explains how to set a different username for uploading packages using GitHub Actions.

with:
  user: guido
  password: ${{ secrets.DEVPI_PASSWORD }}