twine

Follow these steps to build and upload your distributions. It is recommended to upload to Test PyPI first to verify your package before releasing it to the main PyPI repository.

1. Build your distributions: Use a build frontend like build to create your source and binary artifacts.
2. Upload to Test PyPI: Use the -r testpypi flag to target the test repository.
3. Upload to PyPI: Once verified, upload to the production repository.

Note: When prompted for credentials, Twine will not display characters as you type your password.

Instead of entering passwords manually, Twine can use the keyring library to store and retrieve credentials securely.

To set an API token for PyPI, use the keyring set command with the PyPI upload URL and the __token__ username.

Note for Linux users: In headless environments (like servers), additional steps may be required to ensure Keyring can store secrets securely.

Install Twine using pip to begin publishing Python packages to PyPI or other repositories.

pip install twine

If the presence of Keyring causes unexpected prompts or if you prefer to be prompted for a password manually, you can disable Keyring functionality entirely.

keyring --disable

Twine can use a proxy by setting standard proxy environment variables. You can set these for the specific Twine command without exporting them to your entire shell session.

HTTPS_PROXY=socks5://user:pass@host:port twine upload dist/*

Twine's CLI is extensible. To add a new command to the twine binary, you must register an entry point in your package's metadata under the group twine.registered_commands.

When a command is invoked, twine loads the entry point and calls the resulting function, passing any remaining command-line arguments (the args remainder) to it.

Trusted Publishing allows CI systems to authenticate with PyPI using OpenID Connect (OIDC) without long-lived secrets.

When a Resolver detects that it should use Trusted Publishing (e.g., when the username is __token__ on PyPI and no explicit password is provided), it performs the following steps:

1. Fetches the audience from https://{repository_domain}/_/oidc/audience.
2. Detects the OIDC token from the ambient environment (e.g., GitHub Actions).
3. Exchanges the OIDC token for a PyPI upload token via https://{repository_domain}/_/oidc/mint-token.
4. Caches the token and automatically renews it if it is within 5 minutes of expiration (TOKEN_RENEWAL_THRESHOLD).

If the environment does not support OIDC, it falls back to prompting for an API token.

The Repository class encapsulates a requests.Session object.

• Authentication: Authentication is set during __init__. If a username or password is provided, it is stored as a tuple in self.session.auth. If both are empty/None, auth is set to None.
• Lifecycle: Users should call .close() on the Repository instance to properly close the underlying requests.Session and release resources.

Twine provides two primary commands for managing package distributions:

• twine upload: Uploads one or more distributions to a specified repository.
• twine check: Validates whether your distribution's long description will render correctly on PyPI.