Publishing a Python Package to PyPI with GitHub Actions

This guide walks through setting up a Python package with pyproject.toml, configuring GitHub Actions, and publishing automatically to PyPI using tags.

1. Create a pyproject.toml

This file defines your package metadata and build system.

[build-system]
requires = ["setuptools>=61", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
name = "your-package-name"
dynamic = ["version"]
description = "Short description of your package"
readme = "README.md"
authors = [{ name = "Your Name", email = "you@example.com" }]
license = { text = "MIT" }
requires-python = ">=3.9"

dependencies = [
    "numpy",
    "qiskit",
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black",
]

[project.urls]
Homepage = "https://github.com/yourname/your-repo"

[tool.setuptools_scm]
Note: The version is handled automatically by setuptools-scm using Git tags.

2. (Optional) Add src/ layout support

If your package lives inside a src/ directory, add this to the bottom of pyproject.toml:

[tool.setuptools.packages.find]
where = ["src"]
When to use this: Only if your structure is like src/your_package/ instead of placing the package at the root.

3. Create GitHub Actions workflow

Create the folder:

.github/workflows/

Inside it, create a file (e.g. publish.yml):

name: Publish to PyPI

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest

    environment:
      name: pypi

    permissions:
      id-token: write   # for trusted publishing

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install build tool
        run: pip install build

      - name: Build
        run: python -m build

      - name: Publish
        uses: pypa/gh-action-pypi-publish@release/v1

4. Enable PyPI Trusted Publishing

Go to: https://pypi.org/manage/account/publishing/

Add your GitHub repository there.

Important:

5. Publish your package

Once everything is set up, run:

git add .
git commit -m "commit message"
git tag v0.0.1
git push origin main --tags
What happens: Pushing a tag like v0.0.1 triggers GitHub Actions, which builds and publishes your package automatically.

6. Verify the release

After the workflow runs, your package should appear on PyPI:

pip install your-package-name
Common pitfalls: