Skip to main content
← Back to workflows

How to Upload Python Packages to PyPI in GitHub Actions

pypa-gh-action-pypi-publish -
GitHub Action
v1.8.14
906
Contributors
Contributor - webknjazContributor - woodruffw
Categories
CICUBE ANALYTICS INSIGHTS
Engineering Velocity: 25% Team Time Lost to CI Issues
View Platform →
3.5h
Time Saved/Dev/Week
40%
Faster Releases
Click for next insight
Usage
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

gh-action-pypi-publish logo

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 }}