PyPI Deployment

This page documents deployments using dpl v1 which is currently the legacy version. The dpl v2 is released, and we recommend useig it. Please see our blog post for details. dpl v2 documentation can be found here.

Travis CI can automatically release your Python package to PyPI after a successful build.

For a minimal configuration, generate PyPI API token and add the following to your .travis.yml:

deploy:
  provider: pypi
  username: "__token__"
  password: "Your PyPI API token, including the pypi- prefix"

However, this would expose your PyPI API token to the world. We recommend you encrypt your password and add it to your .travis.yml by running:

travis encrypt your-api-token --add deploy.password

If you are using travis-ci.com and not travis-ci.org, you need to add the --com argument to switch the Travis API endpoint:

travis encrypt your-api-token --add deploy.password --com

deploy:
  provider: pypi
  username: "__token__"
  password:
    secure: "Your encrypted token"

It is also possible, but not recommended, to use PyPI user and password, instead of token.

Note that if your PyPI password contains special characters you need to escape them before encrypting your password. Some people have reported difficulties connecting to PyPI with passwords containing anything except alphanumeric characters.

Deploy on Tags #

Most likely, you would only want to deploy to PyPI when a new version of your package is cut. To do this, you can tell Travis CI to only deploy on tagged commits, like so:

deploy:
  provider: pypi
  username: ...
  password: ...
  on:
    tags: true

If you tag a commit locally, remember to run git push --tags to ensure that your tags are uploaded to GitHub.

Deploy Specific Branches #

You can explicitly specify the branch to release from with the on option:

deploy:
  provider: pypi
  username: ...
  password: ...
  on:
    branch: production

Alternatively, you can also configure Travis CI to release from all branches:

deploy:
  provider: pypi
  username: ...
  password: ...
  on:
    all_branches: true

By default, Travis CI will only release from the master branch.

Builds triggered from Pull Requests will never trigger a release.

Release to a self-hosted PyPI #

To release to a different PyPI index:

deploy:
  provider: pypi
  username: ...
  password: ...
  server: https://mypackageindex.com/index

Upload different distributions #

By default, only a source distribution (‘sdist’) will be uploaded to PyPI. If you would like to upload different distributions, specify them using the distributions option, like this:

deploy:
  provider: pypi
  username: ...
  password: ...
  distributions: "sdist bdist_wheel" # Your distributions here

If you specify bdist_wheel in the distributions, the wheel package will automatically be installed.

Upload artifacts only once #

By default, Travis CI runs the deploy stage for each python and environment that you specify. Many of these will generate competing build artifacts that will fail to upload to pypi with a message something like this:

HTTPError: 400 Client Error: File already exists. See https://pypi.org/help/#file-name-reuse for url: https://upload.pypi.org/legacy/

To avoid this, use the skip_existing flag:

deploy:
  provider: pypi
  username: ...
  password: ...
  skip_existing: true

Release build artifacts #

After your tests ran and before the release, Travis CI will clean up any additional files and changes you made.

Maybe that is not what you want, as you might generate some artifacts that are supposed to be released, too. There is now an option to skip the clean up:

deploy:
  provider: pypi
  username: ...
  password: ...
  skip_cleanup: true

Conditional Releases #

You can deploy only when certain conditions are met. See Conditional Releases with on:.

Run Commands Before or After Release #

Sometimes, you want to run commands before or after releasing a package. You can use the before_deploy and after_deploy stages for this. These will only be triggered if Travis CI is actually pushing a release.

before_deploy: "echo 'ready?'"
deploy:
  ..
after_deploy:
  - ./after_deploy_1.sh
  - ./after_deploy_2.sh