Python 套件發佈至 PyPI 前的 5 項檢查指南

Publishing a Python package to PyPI can be straightforward, but mistakes will happen. Some of them are harder to recover from than others. PyPI's immutable files and permanent deletions mean that certain errors can't be undone. Here are five such mistakes and a simple check to prevent each one.

This guide is aimed at solo maintainers publishing Python packages from GitHub to PyPI.

1. You upload a wheel with files that must not be in it

When a secret, test data, or a large file goes into a wheel, everyone who installs that version gets it.

Check: Before each upload, delete dist/ and build/, then build again:

rm -rf dist build
python -m build
python -m zipfile -l dist/*.whl

Read the file list. Look for .env files, fixtures, and anything large.

2. You find a typo in the project page after the upload

PyPI shows your README as the project page. A broken README gives a bad first page for that version.

Check: Run twine check and fix each warning:

twine check dist/*

Then do one rehearsal on TestPyPI and look at the page there. TestPyPI is a separate service, with its own account and its own publisher settings.

3. A failed upload burns your version number

PyPI does not let you upload the same file name twice. If an upload fails after a partial success, you must publish a new version number.

Check: Rehearse on TestPyPI first. Then install the package from TestPyPI in a new virtual environment and import it.

4. Trusted Publishing fails because of one wrong name

You can publish from a GitHub workflow to PyPI without an API token by using Trusted Publishing. PyPI checks the GitHub owner, repository name, and workflow file name against your setup, plus the environment name if you configured one. If any of these don't match, the publish attempt fails.

Check: Compare the four values on PyPI with your workflow, character by character. Give the publish job this permission:

permissions:
  id-token: write

If the project does not exist on PyPI yet, add a pending publisher.

5. You delete a bad release

Deleting a release on PyPI can break installs for users who are pinned to that exact version. Instead of deleting, yank the release. This keeps it available for pinned installs while skipping it for others by default.

Check: If a release is broken, yank it and publish a new, fixed version with a bumped version number. In your changelog, note what went wrong and why you're releasing a new version.

The short version

1. Do a clean build, then read the wheel file list.
2. Run twine check.
3. Rehearse on TestPyPI.
4. Match the four Trusted Publishing values.
5. Yank a bad release. Do not delete it.

The full checklist

I made a longer version of this as a paid kit: PyPI Release Checklist ($7). It has three parts:

• A 7-step release checklist that you can copy into a release issue
• A CSV of the build, check, and upload commands
• A Trusted Publishing workflow template

It is for Python package authors who publish releases to PyPI from GitHub. It is not for private packages or for teams with a managed release platform.

👉 https://costar6.gumroad.com/l/pypi-release-checklist

The checks listed above are simple and free, and they help you avoid the most irreversible mistakes when publishing to PyPI. For the most up-to-date guidance, refer to the official packaging guide at packaging.python.org. If you run into issues, double-check the tooling and PyPI settings, as they can change over time.

Written with help from AI.