twine

Upload to PyPI

$ twine upload dist/*

$ twine upload [[-r|--repository]] testpypi dist/*

$ twine upload [[-u|--username]] [username] [[-p|--password]] [password] dist/*

$ twine upload --repository-url [repository_url] dist/*

$ twine check dist/*

$ twine upload --config-file [configuration_file] dist/*

$ twine upload --skip-existing dist/*

$ twine upload --verbose dist/*

twine [global-options] <command> [command-options] [arguments]

Common commands:
twine upload [options] <package_files...>
twine check <package_files...>
twine --version
twine --help

--version
    Show the version and exit.

--help
    Show this message and exit.

--config-file <path>
    The path to the configuration file to use. Defaults to ~/.pypirc.

--username <username>
    The username to authenticate with. Defaults to __token__ for PyPI.

--password <password>
    The password or API token to authenticate with.

--repository <name>
    The repository name configured in your .pypirc file. Defaults to pypi.

--repository-url <url>
    The URL of the repository to upload to. Overrides --repository.

--cert <path>
    Path to CA certificate bundle to use.

--client-cert <path>
    Path to a client certificate to use.

--disable-progress-bar
    Disable the progress bar.

upload --sign
    GPG sign files prior to upload.

upload --identity <identity>
    GPG identity used to sign files.

upload --non-interactive
    Do not prompt for input.

upload --skip-existing
    Skip files that already exist on the repository.

upload --comment <comment>
    Add a comment to the upload.

upload --verbose
    Display verbose output.

upload --dry-run
    Do not actually upload the files, just print what would be done.

check --strict
    Fail if any warnings are found during checking.

twine is a utility designed for securely uploading Python packages (wheels and source distributions) to the Python Package Index (PyPI) and other compatible package repositories. It provides essential security features, such as cryptographic signing of distributions (when using GPG) and hash checking, ensuring the integrity and authenticity of uploaded packages. Unlike the deprecated python setup.py upload command, twine uploads files serially and verifies the hashes, making it a more robust and secure choice for Python package distribution. It is widely used by Python developers and automated build systems to publish their libraries and applications to the global Python community.

twine requires internet connectivity to communicate with package repositories. Authentication credentials (username/password or API tokens) are sensitive and should be handled securely, ideally using environment variables or a .pypirc file with restricted permissions. While twine enforces secure upload practices, it does not validate the content or security of the Python packages themselves; that responsibility lies with the package author and the repository's review process.

For enhanced security, it is highly recommended to use PyPI API tokens instead of your username and password. API tokens can be scoped to specific projects and have fine-grained permissions, reducing the risk if compromised. Store them in ~/.pypirc or use the TWINE_PASSWORD environment variable.

twine reads authentication and repository information from a ~/.pypirc file by default. This file allows you to configure multiple repositories and store credentials, making repeated uploads more convenient and secure than typing credentials every time.

Before uploading, it's good practice to run twine check <package_files...> to validate that your distribution files are well-formed and meet PyPI's requirements. This can help catch metadata errors or malformed packages before an actual upload attempt.

twine was created to address security and reliability issues present in the legacy python setup.py upload command. The original method was prone to network issues and lacked robust security features like hash verification. Developed by the Python Packaging Authority (PyPA), twine became the recommended and standard tool for uploading Python distributions to PyPI, significantly improving the security and robustness of the Python package distribution workflow since its inception around 2013-2014.

pip(1): Python package installer., build(1): Build Python packages., python(1): The Python interpreter., pypirc(5): The .pypirc configuration file format.