1TWINE(1) twine TWINE(1)
2
6 twine - twine Documentation
7 Table of Contents
9 · Twine user documentation
10 · Why Should I Use This?
12 · Features
14 · Installation
16 · Using Twine
18 · Keyring Support
20 · Disabling Keyring
22 · Options
24 · twine upload
26 · twine check
28 · twine register
30 · Environment Variables
32 · Resources
34 · Contributing
36 · Code of Conduct
38
40 Twine is a utility for publishing Python packages on PyPI.
41 It provides build system independent uploads of source and binary
43 distribution artifacts for both new and existing projects.
44
46 The goal of twine is to improve PyPI interaction by improving security
47 and testability.
48 The biggest reason to use twine is that it securely authenticates you
50 to PyPI over HTTPS using a verified connection regardless of the under‐
51 lying Python version, while whether or not python setup.py upload will
52 work correctly and securely depends on your build system, your Python
53 version and the underlying operating system.
54 Secondly, it allows you to precreate your distribution files. python
56 setup.py upload only allows you to upload something that you're build‐
57 ing with distutils or setuptools, and created in the same command invo‐
58 cation. This means that you cannot test the exact file you're going to
59 upload to PyPI to ensure that it works before uploading it.
60 Finally, twine allows you to pre-sign your files and pass the .asc
62 files into the command line invocation (twine upload mypro‐
63 ject-1.0.1.tar.gz myproject-1.0.1.tar.gz.asc). This enables you to be
64 assured that you're typing your gpg passphrase into gpg itself and not
65 anything else, since you will be the one directly executing gpg
66 --detach-sign -a <filename>.
67
69 · Verified HTTPS connections
70 · Uploading doesn't require executing setup.py
72 · Uploading files that have already been created, allowing testing of
74 distributions before release
75 · Supports uploading any packaging format (including wheels)
77
79 $ pip install twine
80
82 1. Create some distributions in the normal way:
83 $ python setup.py sdist bdist_wheel
85 2. Upload with twine to Test PyPI and verify things look right. Twine
87 will automatically prompt for your username and password:
88 $ twine upload --repository-url https://test.pypi.org/legacy/ dist/*
90 username: ...
91 password:
92 ...
93 3. Upload to PyPI:
95 $ twine upload dist/*
97 4. Done!
99 More documentation on using twine to upload packages to PyPI is in the
101 Python Packaging User Guide.
102
104 Instead of typing in your password every time you upload a distribu‐
105 tion, Twine allows you to store your username and password securely
106 using keyring.
107 To use the keyring, you must first install the keyring packages:
109 · On Windows and MacOS you just need to install keyring, for example,
111 pip install --user keyring.
112 · On Linux, in addition to the keyring package you also need to ensure
114 the python3-dbus system package is installed. For example, apt
115 install python3-dbus. See Keyring's installation instructions for
116 more details.
117 Once keyring is installed you can use the keyring program to set your
119 username and password to use for each package index (repository) you
120 want to upload to using Twine.
121 To set your username and password for test PyPI run the following com‐
123 mand. keyring will prompt you for your password:
124 $ keyring set https://test.pypi.org/legacy/ your-username
126 # or
127 $ python3 -m keyring set https://test.pypi.org/legacy/ your-username
128 To set your username and password for PyPI run this command, again,
130 keyring will prompt for the password:
131 $ keyring set https://upload.pypi.org/legacy/ your-username
133 # or
134 $ python3 -m keyring set https://upload.pypi.org/legacy/ your-username
135 The next time you run twine it will prompt you for a username and will
137 grab the appropriate password from the keyring.
138 NOTE:
140 If you are using Linux in a headless environment (such as on a
141 server) you'll need to do some additional steps to ensure that
142 Keyring can store secrets securely. See Using Keyring on headless
143 systems.
144 Disabling Keyring
146 In some cases, the presence of keyring may be problemmatic. To disable
147 keyring and defer to a prompt for passwords, uninstall keyring or if
148 that's not an option, you can also configure keyring to be disabled.
149 See twine 338 for a discussion on ways to do that.
151
153 twine upload
154 Uploads one or more distributions to a repository.
155 $ twine upload -h
157 usage: twine upload [-h] [-r REPOSITORY] [--repository-url REPOSITORY_URL]
159 [-s] [--sign-with SIGN_WITH] [-i IDENTITY] [-u USERNAME]
160 [-p PASSWORD] [-c COMMENT] [--config-file CONFIG_FILE]
161 [--skip-existing] [--cert path] [--client-cert path]
162 dist [dist ...]
163 positional arguments:
165 dist The distribution files to upload to the repository
166 (package index). Usually dist/* . May additionally
167 contain a .asc file to include an existing signature
168 with the file upload.
169 optional arguments:
171 -h, --help show this help message and exit
172 -r REPOSITORY, --repository REPOSITORY
173 The repository (package index) to upload the package
174 to. Should be a section in the config file (default:
175 pypi). (Can also be set via TWINE_REPOSITORY
176 environment variable.)
177 --repository-url REPOSITORY_URL
178 The repository (package index) URL to upload the
179 package to. This overrides --repository. (Can also be
180 set via TWINE_REPOSITORY_URL environment variable.)
181 -s, --sign Sign files to upload using GPG.
182 --sign-with SIGN_WITH
183 GPG program used to sign uploads (default: gpg).
184 -i IDENTITY, --identity IDENTITY
185 GPG identity used to sign files.
186 -u USERNAME, --username USERNAME
187 The username to authenticate to the repository
188 (package index) as. (Can also be set via
189 TWINE_USERNAME environment variable.)
190 -p PASSWORD, --password PASSWORD
191 The password to authenticate to the repository
192 (package index) with. (Can also be set via
193 TWINE_PASSWORD environment variable.)
194 -c COMMENT, --comment COMMENT
195 The comment to include with the distribution file.
196 --config-file CONFIG_FILE
197 The .pypirc config file to use.
198 --skip-existing Continue uploading files if one already exists. (Only
199 valid when uploading to PyPI. Other implementations
200 may not support this.)
201 --cert path Path to alternate CA bundle (can also be set via
202 TWINE_CERT environment variable).
203 --client-cert path Path to SSL client certificate, a single file
204 containing the private key and the certificate in PEM
205 format.
206 twine check
208 Checks whether your distributions long description will render cor‐
209 rectly on PyPI.
210 $ twine check -h
212 usage: twine check [-h] dist [dist ...]
213 positional arguments:
215 dist The distribution files to check, usually dist/*
216 optional arguments:
218 -h, --help show this help message and exit
219 twine register
221 WARNING: The register command is no longer necessary if you are upload‐
222 ing to pypi.org. As such, it is no longer supported in Warehouse (the
223 new PyPI software running on pypi.org). However, you may need this if
224 you are using a different package index.
225 For completeness, its usage:
227 $ twine register -h
229 usage: twine register [-h] -r REPOSITORY [--repository-url REPOSITORY_URL]
231 [-u USERNAME] [-p PASSWORD] [-c COMMENT]
232 [--config-file CONFIG_FILE] [--cert path]
233 [--client-cert path]
234 package
235 positional arguments:
237 package File from which we read the package metadata.
238 optional arguments:
240 -h, --help show this help message and exit
241 -r REPOSITORY, --repository REPOSITORY
242 The repository (package index) to register the package
243 to. Should be a section in the config file. (Can also
244 be set via TWINE_REPOSITORY environment variable.)
245 Initial package registration no longer necessary on
246 pypi.org:
247 https://packaging.python.org/guides/migrating-to-pypi-
248 org/
249 --repository-url REPOSITORY_URL
250 The repository (package index) URL to register the
251 package to. This overrides --repository. (Can also be
252 set via TWINE_REPOSITORY_URL environment variable.)
253 -u USERNAME, --username USERNAME
254 The username to authenticate to the repository
255 (package index) as. (Can also be set via
256 TWINE_USERNAME environment variable.)
257 -p PASSWORD, --password PASSWORD
258 The password to authenticate to the repository
259 (package index) with. (Can also be set via
260 TWINE_PASSWORD environment variable.)
261 -c COMMENT, --comment COMMENT
262 The comment to include with the distribution file.
263 --config-file CONFIG_FILE
264 The .pypirc config file to use.
265 --cert path Path to alternate CA bundle (can also be set via
266 TWINE_CERT environment variable).
267 --client-cert path Path to SSL client certificate, a single file
268 containing the private key and the certificate in PEM
269 format.
270 Environment Variables
272 Twine also supports configuration via environment variables. Options
273 passed on the command line will take precedence over options set via
274 environment variables. Definition via environment variable is helpful
275 in environments where it is not convenient to create a .pypirc file,
276 such as a CI/build server, for example.
277 · TWINE_USERNAME - the username to use for authentication to the repos‐
279 itory.
280 · TWINE_PASSWORD - the password to use for authentication to the repos‐
282 itory.
283 · TWINE_REPOSITORY - the repository configuration, either defined as a
285 section in .pypirc or provided as a full URL.
286 · TWINE_REPOSITORY_URL - the repository URL to use.
288 · TWINE_CERT - custom CA certificate to use for repositories with
290 self-signed or untrusted certificates.
291
293 · IRC (#pypa - irc.freenode.net)
294 · GitHub repository
296 · User and developer documentation
298 · Python Packaging User Guide
300
302 See our developer documentation for how to get started, an architec‐
303 tural overview, and our future development plans.
304
306 Everyone interacting in the twine project's codebases, issue trackers,
307 chat rooms, and mailing lists is expected to follow the PyPA Code of
308 Conduct.
309 Contributing
311 We are happy you have decided to contribute to twine.
312 Please see the GitHub repository for code and more documentation, and
314 the official Python Packaging User Guide for user documentation. You
315 can also join #pypa or #pypa-dev on Freenode, or the pypa-dev mailing
316 list, to ask questions or get involved.
317 Getting started
319 We recommend you use a development environment. Using a virtualenv
320 keeps your development environment isolated, so twine and its dependen‐
321 cies do not interfere with other packages installed on your machine.
322 You can use virtualenv or pipenv to isolate your development environ‐
323 ment.
324 Clone the twine repository from GitHub, and then make and activate a
326 virtual environment that uses Python 3.6 as the default Python. Exam‐
327 ple:
328 mkvirtualenv -p /usr/bin/python3.6 twine
330 Then, run the following command:
332 pip install -e /path/to/your/local/twine
334 Now, in your virtual environment, twine is pointing at your local copy,
336 so when you make changes, you can easily see their effect.
337 Building the documentation
339 Additions and edits to twine's documentation are welcome and appreci‐
340 ated.
341 We use tox to build docs. Activate your virtual environment, then
343 install tox.
344 pip install tox
346 If you are using pipenv to manage your virtual environment, you may
348 need the tox-pipenv plugin so that tox can use pipenv environments
349 instead of virtualenvs.
350 After making docs changes, lint and build the docs locally, using tox,
352 before making a pull request. Activate your virtual environment, then,
353 in the root directory, run:
354 tox -e docs
356 The HTML of the docs will be visible in twine/docs/_build/.
358 Testing
360 Tests with twine are run using tox, and tested against the following
361 Python versions: 2.7, 3.4, 3,5, and 3.6. To run these tests locally,
362 you will need to have these versions of Python installed on your
363 machine.
364 Either use tox to build against all supported Python versions (if you
366 have them installed) or use tox -e py{version} to test against a spe‐
367 cific version, e.g., tox -e py27 or tox -e py34.
368 Also, always run tox -e lint before submitting a pull request.
370 Submitting changes
372 1. Fork the GitHub repository.
373 2. Make a branch off of master and commit your changes to it.
375 3. Run the tests with tox and lint any docs changes with tox -e docs.
377 4. Ensure that your name is added to the end of the AUTHORS file using
379 the format Name <email@domain.com> (url), where the (url) portion is
380 optional.
381 5. Submit a pull request to the master branch on GitHub.
383 Architectural overview
385 Twine is a command-line tool for interacting with PyPI securely over
386 HTTPS. Its three purposes are to be:
387 1. A user-facing tool for publishing on pypi.org
389 2. A user-facing tool for publishing on other Python package indexes
391 (e.g., devpi instances)
392 3. A useful API for other programs (e.g., zest.releaser) to call for
394 publishing on any Python package index
395 Currently, twine has two principal functions: uploading new packages
397 and registering new projects (register is no longer supported on PyPI,
398 and is in Twine for use with other package indexes).
399 Its command line arguments are parsed in twine/cli.py. The code for
401 registering new projects is in twine/commands/register.py, and the code
402 for uploading is in twine/commands/upload.py. The file twine/package.py
403 contains a single class, PackageFile, which hashes the project files
404 and extracts their metadata. The file twine/repository.py contains the
405 Repository class, whose methods control the URL the package is uploaded
406 to (which the user can specify either as a default, in the .pypirc
407 file, or pass on the command line), and the methods that upload the
408 package securely to a URL.
409 Where Twine gets configuration and credentials
411 A user can set the repository URL, username, and/or password via com‐
412 mand line, .pypirc files, environment variables, and keyring.
413 Adding a maintainer
415 A checklist for adding a new maintainer to the project.
416 1. Add her as a Member in the GitHub repo settings. (This will also
418 give her privileges on the Travis CI project.)
419 2. Get her Test PyPI and canon PyPI usernames and add her as a Main‐
421 tainer on our Test PyPI project and canon PyPI.
422 Making a new release
424 A checklist for creating, testing, and distributing a new version.
425 1. Choose a version number, e.g., "1.15."
427 2. Merge the last planned PR before the new release:
429 1. Add new changes to docs/changelog.rst.
431 2. Update the __version__ string in twine/__init__.py, which is
433 where setup.py pulls it from, with {number}rc1 for "release can‐
434 didate 1".
435 3. Update copyright dates.
437 3. Run Twine tests:
439 1. tox -e py{27,34,35,36,py}
441 2. tox -e lint for the linter
443 3. tox -e docs (this checks the Sphinx docs and uses readme_ren‐
445 derer to check that the long_description and other metadata will
446 render fine on the PyPI description)
447 4. Run integration tests with downstreams:
449 1. Test pypiserver support:
451 git clone git@github.com:pypiserver/pypiserver
453 cd pypiserver
454 tox -e pre_twine
455 2. Create a test package to upload to Test PyPI, version-control it
457 with git, and test zest.releaser per directions in this comment.
458 3. Test devpi support:
460 pip install devpi-client
462 devpi use https://m.devpi.net
463 devpi user -c {username} password={password}
464 devpi login {username} --password={password}
465 devpi index -c testpypi type=mirror mirror_url=https://test.pypi.org/simple/
466 devpi use {username}/testpypi
467 python setup.py sdist
468 twine upload --repository-url https://m.devpi.net/{username}/testpypi/ dist/{testpackage}.tar.gz
469 5. Create a git tag with git tag -sam 'Release v{number}' {number}.
471 · {number}, such as 1.15.1rc1
473 · -s signs it with your PGP key
475 · -a creates an annotated tag for GitHub
477 · -m adds the message; optional if you want to compose a longer
479 message
480 6. View your tag: git tag -v {number}
482 7. Push your tag: git push upstream {number}.
484 8. Delete old distributions: rm dist/*.
486 9. Create distributions with python setup.py sdist bdist_wheel.
488 10. Set your TestPyPI and canon PyPI credentials in your session with
490 keyring (docs forthcoming).
491 11. Upload to Test PyPI: twine upload --repository-url
493 https://test.pypi.org/legacy/ --skip-existing dist/*
494 12. Verify that everything looks good, downloads ok, etc. Make needed
496 fixes.
497 13. Merge the last PR before the new release:
499 1. Add new changes and new release to docs/changelog.rst, with the
501 new version {number}, this time without the rc1 suffix.
502 2. Update the __version__ string in twine/__init__.py with {num‐
504 ber}.
505 14. Run tests again. Check the changelog to verify that it looks right.
507 15. Create a new git tag with git tag -sam 'Release v{number}' {num‐
509 ber}.
510 16. View your tag: git tag -v {number}
512 17. Push your tag: git push upstream {number}.
514 18. Delete old distributions: rm dist/*.
516 19. Create distributions with python setup.py sdist bdist_wheel.
518 20. On a Monday or Tuesday, upload to canon PyPI: twine upload
520 --skip-existing dist/*
521 NOTE:
523 Will be replaced by tox -e release at some point.
524 21. Send announcement email to pypa-dev mailing list and celebrate.
526 Future development
528 See our open issues.
529 In the future, pip and twine may merge into a single tool; see ongoing
531 discussion.
532 Changelog
534 ·
535 #367: Avoid MD5 when Python is compiled in FIPS mode
536 ·
538 #408: Fix regression where keyring is unconditionally disabled.
539 ·
541 #404: Fix regression with upload exit code
542 ·
544 #363: Empower --skip-existing for Artifactory repositories
545 ·
547 #392: Drop support for Python 3.3
548 ·
550 #395: Add twine check command to check long description
551 ·
553 #319: Support Metadata 2.1 (PEP 566), including Markdown for
554 description fields.
555 ·
557 #320: Remove PyPI as default register package index.
558 ·
560 #322: Raise exception if attempting upload to deprecated legacy PyPI
561 URLs.
562 ·
564 #269: Avoid uploading to PyPI when given alternate repository URL,
565 and require http:// or https:// in repository_url.
566 ·
568 #318: Update PyPI URLs.
569 ·
571 #314: Add new maintainer, release checklists.
572 ·
574 #277: Add instructions on how to use keyring.
575 ·
577 #256: Improve progressbar
578 ·
580 #257: Declare support for Python 3.6
581 ·
583 #303: Revise docs predicting future of twine
584 ·
586 #296: Add architecture overview to docs
587 ·
589 #295: Add doc building instructions
590 ·
592 #46: Link to changelog from README
593 ·
595 #304: Reorganize & improve user & developer documentation.
596 ·
598 #265: Fix --repository[-url] help text
599 ·
601 #268: Print progress to stdout, not stderr
602 ·
604 #297: Fix Read the Docs, tox, Travis configuration
605 ·
607 #286: Fix Travis CI and test configuration
608 ·
610 #200: Remove obsolete registration guidance
611 ·
613 #299: Fix changelog formatting
614 ·
616 #298: Fix syntax highlighting in README
617 ·
619 #315: Degrade gracefully when keyring is unavailable
620 · : Blacklist known bad versions of Requests. See also #253:
622 · : Check if a package exists if the URL is one of:
624 · https://pypi.python.org/pypi/
626 · https://upload.pypi.org/
628 · https://upload.pypi.io/
630 This helps people with https://upload.pypi.io still in their
632 .pypirc file.
633 · : Fix precedence of --repository-url over --repository. See also
635 #206:
636 · : Fix --skip-existing when used to upload a package for the first
638 time. See also #220:
639 · : Twine sends less information about the user's system in the
641 User-Agent string. See also #229:
642 · : Twine will use hashlib.blake2b on Python 3.6+ instead of using
644 pyblake2 for Blake2 hashes 256 bit hashes.
645 · : Twine will now resolve passwords using the keyring if available.
647 Module can be required with the keyring extra.
648 ·
650 #171: Generate Blake2b 256 digests for packages if pyblake2 is
651 installed. Users can use python -m pip install twine[with-blake2] to
652 have pyblake2 installed with Twine.
653 ·
655 #166: Allow the Repository URL to be provided on the command-line
656 (--repository-url) or via an environment variable (TWINE_REPOSI‐
657 TORY_URL).
658 ·
660 #144: Retrieve configuration from the environment as a default.
661 · Repository URL will default to TWINE_REPOSITORY
663 · Username will default to TWINE_USERNAME
665 · Password will default to TWINE_PASSWORD
667 ·
669 #201: Switch from upload.pypi.io to upload.pypi.org.
670 · : Do not generate traffic to Legacy PyPI unless we're uploading to
672 it or uploading to Warehouse (e.g., pypi.io). This avoids the attempt
673 to upload a package to the index if we can find it on Legacy PyPI
674 already.
675 · : Warn users if they receive a 500 error when uploading to
677 *pypi.python.org
678 · : Stop testing on Python 2.6. 2.6 support will be "best effort"
680 until 2.0.0
681 · : Generate SHA256 digest for all packages by default.
683 · : Correct a packaging error.
685 ·
687 #195: Fix uploads to instances of pypiserver using --skip-existing.
688 We were not properly checking the return status code on the response
689 after attempting an upload.
690 ·
692 #189:, #191: Fix issue where we were checking the existence of
693 packages even if the user didn't specify --skip-existing.
694 ·
696 #187: Clint was not specified in the wheel metadata as a dependency.
697 ·
699 #177: Switch Twine to upload to pypi.io instead of pypi.python.org.
700 ·
702 #167: Implement retries when the CDN in front of PyPI gives us a 5xx
703 error.
704 ·
706 #162: Allow --skip-existing to work for 409 status codes.
707 ·
709 #152: Add progress bar to uploads.
710 ·
712 #142: Support --cert and --client-cert command-line flags and config
713 file options for feature parity with pip. This allows users to verify
714 connections to servers other than PyPI (e.g., local package reposito‐
715 ries) with different certificates.
716 ·
718 #186: Allow passwords to have %s in them.
719 ·
721 #155: Bump requests-toolbelt version to ensure we avoid Connection‐
722 Errors
723 ·
725 #146: Exception while accessing the respository key (sic) when rais‐
726 ing a redirect exception.
727 ·
729 #145: Paths with hyphens in them break the Wheel regular expression.
730 ·
732 #137:, #140: Uploading signatures was broken due to the pull
733 request that added large file support via requests-toolbelt. This
734 caused a 500 error on PyPI and prevented package and signature upload
735 in twine 1.6.0
736 ·
738 #132: Upload signatures with packages appropriately
739 As part of the refactor for the 1.6.0 release, we were using the
740 wrong name to find the signature file.
741 This also uncovered a bug where if you're using twine in a situa‐
743 tion where * is not expanded by your shell, we might also miss
744 uploading signatures to PyPI. Both were fixed as part of this.
745 ·
747 #130: Fix signing support for uploads
748 ·
750 #8: Support registering new packages with twine register
751 ·
753 #115: Add the --skip-existing flag to twine upload to allow users to
754 skip releases that already exist on PyPI.
755 ·
757 #97: Allow the user to specify the location of their .pypirc
758 ·
760 #104: Large file support via the requests-toolbelt
761 ·
763 #106: Upload wheels first to PyPI
764 ·
766 #111: Provide more helpful messages if .pypirc is out of date.
767 ·
769 #116: Work around problems with Windows when using getpass.getpass
770 ·
772 #114: Warnings triggered by pkginfo searching for PKG-INFO files
773 should no longer be user visible.
774 ·
776 #92: Raise an exception on redirects
777 ·
779 #29: Support commands not named "gpg" for signing
780 ·
782 #61: Support deprecated pypirc file format
783 ·
785 #85: Display information about the version of setuptools installed
786 · : Add lower-limit to requests dependency
788 ·
790 #6: Switch to a git style dispatching for the commands to enable
791 simpler commands and programmatic invocation.
792 ·
794 #13: Parse ~/.pypirc ourselves and use subprocess instead of the
795 distutils.spawn module.
796 ·
798 #65: Expand globs and check for existence of dists to upload
799 ·
801 #26: Add support for uploading Windows installers
802 ·
804 #47: Fix issue uploading packages with _s in the name
805 ·
807 #32: Use pkg_resources to load registered commands
808 ·
810 #34: List registered commands in help text
811 ·
813 #28: Prevent ResourceWarning from being shown
814 · : Additional functionality.
816 · : Basic functionality.
818 · search
820
822 Donald Stufft, Individual contributors
823
825 2018, Donald Stufft and individual contributors
8261.12 Feb 02, 2019 TWINE(1)