# Twine: Python Package Upload Tool


Twine is a command-line tool for uploading Python distribution files ([sdists](https://pydevtools.com/handbook/reference/sdist.md) and [wheels](https://pydevtools.com/handbook/reference/wheel.md)) to [PyPI](https://pydevtools.com/handbook/explanation/what-is-pypi.md) 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](https://pydevtools.com/handbook/reference/build.md) or [setuptools](https://pydevtools.com/handbook/reference/setuptools.md) and need a standalone upload step. Tools like [uv](https://pydevtools.com/handbook/reference/uv.md), [poetry](https://pydevtools.com/handbook/reference/poetry.md), [flit](https://pydevtools.com/handbook/reference/flit.md), [hatch](https://pydevtools.com/handbook/reference/hatch.md), and [pdm](https://pydevtools.com/handbook/reference/pdm.md) 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](https://pydevtools.com/handbook/tutorial/publishing-your-first-python-package-to-pypi.md) for a walkthrough.

## Usage

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

```console
$ 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](https://test.pypi.org) before publishing to the real index:

```console
$ twine upload --repository testpypi dist/*
```

### Check packages before uploading

Validate that distribution files will be accepted by PyPI:

```console
$ 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:

```ini
[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](https://pydevtools.com/handbook/explanation/why-use-trusted-publishing-for-pypi.md) eliminates the need to store tokens entirely.

## Installation

```console
$ pip install twine
```

Or with [pipx](https://pydevtools.com/handbook/reference/pipx.md) for an isolated install:

```console
$ pipx install twine
```

## Learn More

### Handbook guides

- [Publishing Your First Python Package to PyPI](https://pydevtools.com/handbook/tutorial/publishing-your-first-python-package-to-pypi.md) walks through the full build-and-upload workflow using uv
- [Why Use Trusted Publishing for PyPI?](https://pydevtools.com/handbook/explanation/why-use-trusted-publishing-for-pypi.md) explains why stored API tokens are a security risk
- [How to publish to PyPI with trusted publishing](https://pydevtools.com/handbook/how-to/how-to-publish-to-pypi-with-trusted-publishing.md) sets up token-free publishing from CI
- [What is PyPI?](https://pydevtools.com/handbook/explanation/what-is-pypi.md) covers the Python Package Index
- [build reference](https://pydevtools.com/handbook/reference/build.md) documents the package build tool that pairs with Twine

### Official documentation

- [Twine documentation](https://twine.readthedocs.io/)
- [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/) from the Python Packaging User Guide