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 a username and password. PyPI removed password-based authentication in April 2024; the username must be __token__ and the password an API token starting with pypi-. 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...Warning
API tokens stored in .pypirc are long-lived secrets. For CI pipelines, trusted publishing eliminates the need to store tokens entirely.
Installation
For a one-off upload, run Twine without installing it:
$ uvx twine upload dist/*
For a persistent install:
$ 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