twine

Twine is a utility for publishing packages on PyPI.

Currently it only supports registering projects and uploading distributions.

Why Should I Use This?

The goal of twine is to improve PyPI interaction by improving security and testability.

The biggest reason to use twine is that it securely authenticates you to PyPI over HTTPS using a verified connection, while python setup.py upload only recently stopped using HTTP in Python 2.7.9+ and Python 3.2+. This means anytime you use python setup.py upload with an older Python version, you expose your username and password to being easily sniffed. Twine uses only verified TLS to upload to PyPI, protecting your credentials from theft.

Secondly, it allows you to precreate your distribution files. python setup.py upload only allows you to upload something that you've created in the same command invocation. This means that you cannot test the exact file you're going to upload to PyPI to ensure that it works before uploading it.

Finally, it allows you to pre-sign your files and pass the .asc files into the command line invocation (twine upload twine-1.0.1.tar.gz twine-1.0.1.tar.gz.asc). This enables you to be assured that you're typing your gpg passphrase into gpg itself and not anything else, since you will be the one directly executing gpg --detach-sign -a <filename>.

Features

• Verified HTTPS connections
• Uploading doesn't require executing setup.py
• Uploading files that have already been created, allowing testing of distributions before release
• Supports uploading any packaging format (including wheels)

Installation

$ pip install twine

Usage

1. Create some distributions in the normal way:

   $ python setup.py sdist bdist_wheel

2. Upload with twine:

   $ twine upload dist/*

3. Done!

More documentation on using twine to upload packages to PyPI is in the Python Packaging User Guide.

Options

$ twine upload -h

usage: twine upload [-h] [-r REPOSITORY] [--repository-url REPOSITORY_URL]
                    [-s] [--sign-with SIGN_WITH] [-i IDENTITY] [-u USERNAME]
                    [-p PASSWORD] [-c COMMENT] [--config-file CONFIG_FILE]
                    [--skip-existing] [--cert path] [--client-cert path]
                    dist [dist ...]

positional arguments:
  dist                  The distribution files to upload to the repository,
                        may additionally contain a .asc file to include an
                        existing signature with the file upload

optional arguments:
  -h, --help            show this help message and exit
  -r REPOSITORY, --repository REPOSITORY
                        The repository to upload the package to. Can be a
                        section in the config file or a full URL to the
                        repository (default: pypi). (Can also be set via
                        TWINE_REPOSITORY environment variable)
  --repository-url REPOSITORY_URL
                        The repository URL to upload the package to. This can
                        be specified with --repository because it will be used
                        if there is no configuration for the value passed to
                        --repository. (Can also be set via
                        TWINE_REPOSITORY_URL environment variable.)
  -s, --sign            Sign files to upload using gpg
  --sign-with SIGN_WITH
                        GPG program used to sign uploads (default: gpg)
  -i IDENTITY, --identity IDENTITY
                        GPG identity used to sign files
  -u USERNAME, --username USERNAME
                        The username to authenticate to the repository as (can
                        also be set via TWINE_USERNAME environment variable)
  -p PASSWORD, --password PASSWORD
                        The password to authenticate to the repository with
                        (can also be set via TWINE_PASSWORD environment
                        variable)
  -c COMMENT, --comment COMMENT
                        The comment to include with the distribution file
  --config-file CONFIG_FILE
                        The .pypirc config file to use
  --skip-existing       Continue uploading files if one already exists. (Only
                        valid when uploading to PyPI. Other implementations
                        may not support this.)
  --cert path           Path to alternate CA bundle (can also be set via
                        TWINE_CERT environment variable)
  --client-cert path    Path to SSL client certificate, a single file
                        containing the private key and the certificate in PEM
                        format

Twine also includes a register command.

Warning

register is no longer necessary if you are uploading to pypi.org. As such, it is no longer supported in Warehouse (the new PyPI software running on pypi.org). However, you may need this if you are using a different package index.

For completeness, its usage:

$ twine register -h
usage: twine register [-h] [-r REPOSITORY] [--repository-url REPOSITORY_URL]
                      [-u USERNAME] [-p PASSWORD] [-c COMMENT]
                      [--config-file CONFIG_FILE] [--cert path]
                      [--client-cert path]
                      package

positional arguments:
  package               File from which we read the package metadata

optional arguments:
  -h, --help            show this help message and exit
  -r REPOSITORY, --repository REPOSITORY
                        The repository to register the package to. Can be a
                        section in the config file or a full URL to the
                        repository (default: pypi). (Can also be set via
                        TWINE_REPOSITORY environment variable)
  --repository-url REPOSITORY_URL
                        The repository URL to upload the package to. This can
                        be specified with --repository because it will be used
                        if there is no configuration for the value passed to
                        --repository. (Can also be set via
                        TWINE_REPOSITORY_URL environment variable.)
  -u USERNAME, --username USERNAME
                        The username to authenticate to the repository as (can
                        also be set via TWINE_USERNAME environment variable)
  -p PASSWORD, --password PASSWORD
                        The password to authenticate to the repository with
                        (can also be set via TWINE_PASSWORD environment
                        variable)
  -c COMMENT, --comment COMMENT
                        The comment to include with the distribution file
  --config-file CONFIG_FILE
                        The .pypirc config file to use
  --cert path           Path to alternate CA bundle (can also be set via
                        TWINE_CERT environment variable)
  --client-cert path    Path to SSL client certificate, a single file
                        containing the private key and the certificate in PEM
                        format

Environment Variables

Twine also supports configuration via environment variables. Options passed on the command line will take precedence over options set via environment variables. Definition via environment variable is helpful in environments where it is not convenient to create a .pypirc file, such as a CI/build server, for example.

• TWINE_USERNAME - the username to use for authentication to the repository
• TWINE_PASSWORD - the password to use for authentication to the repository
• TWINE_REPOSITORY - the repository configuration, either defined as a section in .pypirc or provided as a full URL
• TWINE_REPOSITORY_URL - the repository URL to use
• TWINE_CERT - custom CA certificate to use for repositories with self-signed or untrusted certificates

Resources

• IRC (#pypa - irc.freenode.net)
• GitHub repository
• User and developer documentation
• Python Packaging User Guide

Contributing

See our developer documentation for how to get started, an architectural overview, and our future development plans.

Code of Conduct

Everyone interacting in the twine project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PyPA Code of Conduct.