Twine API Tokens vs Password Auth: Choosing the Right PyPI Upload Credential for Automated Pipelines

Question

Choosing an Authentication Strategy for Automated PyPI Uploads

When configuring Twine to publish Python packages from an automated pipeline, the choice between traditional username/password credentials and scoped API tokens presents a trade-off between setup simplicity and long-term credential hygiene. Both methods authenticate against the same PyPI upload endpoint, so package validation and indexing behavior are identical regardless of which credential type is used.

The constraint is that the pipeline runs on shared infrastructure where secrets must be managed carefully. Password-based authentication requires transmitting the account password on every upload, which may be convenient for ad-hoc local use but raises concerns when embedded in CI variables. API tokens, treated by Twine as a password with the special username __token__, can be scoped and revoked independently of the account password, but they still require secure secret storage to prevent unauthorized uploads if leaked.

Given that both paths produce the same server-side upload event and indexing result, the practical uncertainty is which credential model better fits a team that needs to rotate access regularly and limit blast radius without adding excessive operational overhead.

Should a shared CI pipeline prefer API tokens for revocability and scope control, or is password authentication sufficient when combined with strict environment variable hygiene? How does the choice affect credential rotation workflows when multiple contributors need upload access?

Tasadduq Burney · Answer

Answer
For automated uploads to the official PyPI index, Twine should be configured with an API token. The legacy account password is deprecated for uploads, cannot be scoped, and would expose the entire account if leaked. API tokens are scoped to a project or account, revocable, and fit shared CI runners.
Why Tokens Win

Scope & blast radius – A token can be limited to a single project; a leak only affects that scope.
  Revocation & rotation – Revoke the old token in PyPI, generate a new one, and update the CI secret without changing the primary password.
  Auditability – Separate tokens per contributor make it clear who performed an upload.
  Supported by Twine – Twine treats the token as a password with the username __token__, so the command line stays the same.

Practical Steps for a Shared CI Runner

Generate a tokenGo to PyPI token page, click “Add token”, choose a “Project‑wide” or a specific project scope, and copy the token value.
  Store the token securelyIn your CI platform (GitHub Actions, GitLab CI, Azure Pipelines, etc.), create a secret named e.g. PYPI_TOKEN. Ensure the secret is masked in logs and only exposed to the publish job.
  Configure TwineUse the following command (or add it to your .pypirc):
twine upload --repository-url https://upload.pypi.org/legacy/ -u __token__ -p \"$PYPI_TOKEN\" dist/*
  Verify the uploadRun a dry‑run first:
twine upload --repository-url https://upload.pypi.org/legacy/ --dry-run -u __token__ -p \"$PYPI_TOKEN\" dist/*
  Rotate the tokenWhen a user leaves the team or a token is suspected to be compromised, revoke the old token in the PyPI UI, generate a new one, update the CI secret, and re‑run the pipeline.

When Passwords Might Still Be Relevant
If you are publishing to a private or self‑hosted PyPI index that still accepts legacy password authentication, you must first verify that the index supports API tokens. In that case, consult the index’s documentation to confirm supported credential types.
Question for You
Are you publishing exclusively to the official PyPI index, or are you also targeting a private index that might not support API tokens?

Twine API Tokens vs Password Auth: Choosing the Right PyPI Upload Credential for Automated Pipelines

Choosing an Authentication Strategy for Automated PyPI Uploads

1 answer

Answer

Why Tokens Win

Practical Steps for a Shared CI Runner

When Passwords Might Still Be Relevant

Question for You

Your perspective belongs here.

0 question comments