twine

Warnings

• breaking The `python setup.py upload` command is deprecated and insecure. Twine is the official, secure, and recommended tool for uploading packages to PyPI.
  Fix: Always use `twine upload` instead of `python setup.py upload`. Ensure you build your distribution artifacts first using `python -m build`.
• breaking Since Twine 5.0.0, only `__token__` is supported as a username when uploading to PyPI and TestPyPI. Supplying any other username will cause the upload to fail.
  Fix: When using API tokens, always set the username to `__token__`. Your API token should be used as the password. This applies whether using environment variables (`TWINE_USERNAME`, `TWINE_PASSWORD`), `.pypirc`, or `keyring`.
• breaking Twine 6.0.0 changed the default username behavior for PyPI/TestPyPI. It now defaults to `__token__` and no longer overrides a username configured via environment variables or command line if that username is *not* `__token__`. Workflows that implicitly relied on Twine overriding a non-`__token__` username will now fail.
  Fix: Explicitly set `TWINE_USERNAME='__token__'` (or use `--username __token__` on the CLI) if you intend to use an API token. Do not rely on previous implicit override behavior.
• deprecated The `--skip-existing` flag is no longer supported for non-PyPI upload targets (e.g., custom package indexes). It also no longer submits `md5_digest` field as it's deprecated on PyPI.
  Fix: Remove `--skip-existing` when uploading to non-PyPI repositories. For PyPI, the flag will still work but consider the implications. The `md5_digest` removal is automatic and requires no user action.
• gotcha `twine check dist/*` may fail if your `README` file is not named exactly `README` and you are using the dynamic `readme` option in `pyproject.toml`.
  Fix: Ensure your `README` file is named `README` (e.g., `README.md`) if using `dynamic = ["readme"]` in `pyproject.toml` for metadata. Despite the check failure, the package might still upload successfully, but it's best to resolve the warning for proper rendering.
• gotcha Using `twine upload dist/*` can inadvertently upload older or incorrect distribution files if your `dist/` directory contains multiple versions or unwanted artifacts.
  Fix: Always ensure your `dist/` directory contains only the desired distribution files for the current upload. Consider clearing the `dist/` directory before building new distributions or being more specific with the file path, e.g., `twine upload dist/my_package-1.2.3-*`.

Install

• pip install twine Install twine

Imports

• twine (CLI)

  twine upload dist/*

  Twine is primarily a command-line utility for package publishing. Direct programmatic import of its core upload functionality is not the common or recommended usage pattern for end-users.

Quickstart

This quickstart guides you through building your Python package distributions (sdist and wheel), checking them for common issues, and then uploading them to TestPyPI for verification before a final upload to the official PyPI. It emphasizes using API tokens for authentication via environment variables for security.

# 1. Ensure your distribution files (wheels, sdists) are built:
# (Use `python -m build` as a modern alternative to `python setup.py sdist bdist_wheel`)
python -m build

# 2. (Optional but recommended) Check your package metadata and README rendering:
twine check dist/*

# 3. (Optional but recommended) Upload to TestPyPI first to verify:
# Set TWINE_USERNAME and TWINE_PASSWORD environment variables with your TestPyPI API token
# For example, in bash:
# export TWINE_USERNAME="__token__"
# export TWINE_PASSWORD="pypi-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
# Or, you will be prompted for credentials.
# Replace 'your_test_pypi_api_token' with your actual TestPyPI API token
import os
os.environ['TWINE_USERNAME'] = os.environ.get('TEST_PYPI_USERNAME', '__token__')
os.environ['TWINE_PASSWORD'] = os.environ.get('TEST_PYPI_PASSWORD', 'pypi-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')

print("Uploading to TestPyPI...")
# This command will be run via subprocess in a real application
# For quickstart, it implies running directly in shell:
# !twine upload --repository testpypi dist/*
# In a Python context, you'd use subprocess.run()

# 4. Upload to PyPI (after successful TestPyPI verification):
# Set TWINE_USERNAME and TWINE_PASSWORD environment variables with your PyPI API token
# For example, in bash:
# export TWINE_USERNAME="__token__"
# export TWINE_PASSWORD="pypi-YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
# Or, you will be prompted for credentials.
# Replace 'your_pypi_api_token' with your actual PyPI API token
os.environ['TWINE_USERNAME'] = os.environ.get('PYPI_USERNAME', '__token__')
os.environ['TWINE_PASSWORD'] = os.environ.get('PYPI_PASSWORD', 'pypi-YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY')

print("Uploading to PyPI...")
# !twine upload dist/*