How do you publish a Python package to PyPI using python -m build and twine?

## Publishing is the last mile, and it is not the build Two distinct things get conflated under "publish". **Building** turns your source tree into distribution artifacts — a source distribution archive and one or more wheels — and is the job of a build backend driven by a build frontend. **Publishing** takes those finished files and hands them to an index. `python -m build` does the first; `twine upload` does the second. Keeping them separate matters in practice: it means the exact bytes you tested are the exact bytes you upload, and it means a failed upload never silently rebuilds something different. ## The flow, step by step ```console python -m pip install --upgrade build twine python -m build python -m twine check dist/* python -m twine upload --repository testpypi dist/* python -m twine upload dist/* ``` 1. **Start clean.** `python -m build` builds in an isolated environment, but it does not clean `dist/` for you. A stale wheel left from a previous version is the most common way a release goes out with the wrong contents, because `twine upload dist/*` uploads everything it finds. Delete `dist/` first, and build from a checkout with no local modifications so the artifact corresponds to a tag. 2. **Check the metadata.** `twine check dist/*` renders the long description the way the index will and fails on a README the index cannot display. It is cheap and it catches the single most common first-release embarrassment: a project page that shows raw markup or nothing at all. The README is declared in your project metadata along with its content type; classifiers and the supported-Python constraint travel in the same metadata and drive what the index displays and what an installer will consider. 3. **Rehearse on TestPyPI.** TestPyPI is a separate index with **separate accounts and separate API tokens** — your production credentials do not work there. Upload with `--repository testpypi`, then install the result into a throwaway virtual environment. Because most dependencies do not exist on TestPyPI, that install usually needs the real index as a fallback source. What the rehearsal actually validates is the shape of the release: the project name, the rendered page, that the wheel installs, and that the console commands and imports work from an *installed* package rather than from your source tree. 4. **Upload for real.** `twine upload dist/*`. On success the release appears on the index and is installable within seconds. ## Credentials PyPI does not accept an account password for uploads. You present an **API token**: it goes in the password field, paired with a fixed reserved username rather than your account name, and the token string itself starts with `pypi-`. Tokens can be scoped to a single project, which is what you want — an account-scoped token can publish anything you own. Store it in the CI secret store, or in twine's configuration file, or pass it through twine's environment variables. From CI there is a better answer: **trusted publishing**, where the workflow proves its identity to the index with a short-lived OIDC token and exchanges it for a short-lived, project-scoped upload token. Nothing long-lived is stored anywhere. If you publish from a pipeline, that is the default choice; a stored token is the fallback for machines that cannot mint an identity. ## What you cannot undo The release is **immutable**. Once the index accepts a file, that filename — and by extension that version — is spent forever. You cannot re-upload it with a fix, and deleting it does not free the name. That single fact is why the rehearsal step exists and why `twine check` is worth the two seconds: the cost of noticing a mistake after the upload is a new version number and a yank, not an edit. ## Verifying the release A release is not done because the upload printed a URL. Create a fresh virtual environment on a machine that has never seen your source tree, install the project from the index by name, import it, and run its console command. Installing from a source tree hides an entire class of packaging bugs — missing package data, a module that only imports because the current directory is on the import path, a console command that was never declared. Install from the index, and those surface immediately. ## Alternatives to the two commands `uv publish` uploads the contents of `dist/` and speaks the same protocol and the same trusted publishing exchange; `flit publish` and `poetry publish` bundle build and upload into one command for projects already using those tools. The mechanics — an index that authenticates you, accepts files once, and never lets you change them — are identical whichever frontend you pick. The legacy setuptools upload command is long deprecated and should not be used.