Twine: Python Package Upload Tool

Twine is a command-line tool for uploading Python distribution files (sdists and wheels) to PyPI and compatible package indexes. It replaced the deprecated python setup.py upload command, which transmitted credentials over unencrypted connections.

When to use Twine

Use Twine when you build packages with build or setuptools and need a standalone upload step. Tools like uv, poetry, flit, hatch, and pdm have built-in publish commands that handle uploads directly. If you already use one of those tools, you don’t need Twine.

For new projects, uv publish is the recommended path. See Publishing Your First Python Package to PyPI for a walkthrough.

Usage

Build your package first, then upload the resulting files from dist/:

$ python -m build
$ twine upload dist/*

Twine prompts for your PyPI username and password (or API token). To avoid interactive prompts, set credentials via environment variables or a .pypirc file.

Upload to TestPyPI

Test uploads against TestPyPI before publishing to the real index:

$ twine upload --repository testpypi dist/*

Check packages before uploading

Validate that distribution files will be accepted by PyPI:

$ twine check dist/*

This catches metadata problems (missing description, invalid classifiers) before you attempt an upload.

Configure credentials with .pypirc

Create a ~/.pypirc file to store repository URLs and API tokens:

[pypi]
username = __token__
password = pypi-AgEI...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgEI...

Installation

$ pip install twine

Or with pipx for an isolated install:

$ pipx install twine

Learn More

Handbook guides

• Publishing Your First Python Package to PyPI walks through the full build-and-upload workflow using uv
• Why Use Trusted Publishing for PyPI? explains why stored API tokens are a security risk
• How to publish to PyPI with trusted publishing sets up token-free publishing from CI
• What is PyPI? covers the Python Package Index
• build reference documents the package build tool that pairs with Twine

Official documentation

• Twine documentation
• Packaging Python Projects from the Python Packaging User Guide