Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Dev: Releasing IPython

Thomas Kluyver edited this page · 11 revisions
Clone this wiki locally

This document contains notes about the process that is used to release IPython. Our release process is currently not very formal and could be improved.

Most of the release process is automated by the release script in the tools directory of our main repository. This document is just a handy reminder for the release manager.

0. Environment variables

You can set some env variables to note previous release tag and current release milestone, version, and git tag:


These will be used later if you want to copy/paste, or you can just type the appropriate command when the time comes. These variables are not used by scripts (hence no export).

1. Finish release notes

  • If a major release:

    • merge any pull request notes into what's new:

      python tools/
    • update docs/source/whatsnew/development.rst, to ensure it covers the major points.

    • move the contents of development.rst to versionX.Y.rst
  • generate summary of GitHub contributions, which can be done with:

    python tools/ --milestone $MILESTONE > stats.rst

    which may need some manual cleanup. Add the cleaned up result and add it to docs/source/whatsnew/github-stats-X.Y.rst (make a new file, or add it to the top, depending on whether it is a major release). You can use:

      git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f

    to find duplicates and update .mailmap. Before generating the GitHub stats, verify that all closed issues and pull requests have appropriate milestones. This search should return no results.

2. Run the tools/build_release script

This does all the file checking and building that the real release script will do. This will let you do test installations, check that the build procedure runs OK, etc. You may want to also do a test build of the docs.

3. Create and push the new tag

Edit IPython/core/ to have the current version, and then run jsversion to update the value in Javascript:

python jsversion

Commit the changes to and jsversion:

git commit -am "release $VERSION"
git push origin $BRANCH

Create and push the tag:

git tag -am "release $VERSION" "$TAG"
git push origin --tags

Update back to x.y-dev or x.y-maint, and push:

python jsversion
git commit -am "back to development"
git push origin $BRANCH

4. Get a fresh clone of the tag for building the release:

cd /tmp
git clone --recursive --depth 1 -b "$TAG" 

5. Run the release script

cd tools && ./release

This makes the tarballs, zipfiles, and wheels. It posts them to and registers the release with PyPI.

This will require that you have current wheel, Python 3.4 and Python 2.7, and an appropriate version of LESS.

6. Publish updated docs

Make sure you have all the dependencies, otherwise parts of the API documentation can't be built. Sphinx should warn you if imports fail.

For this we are now using GitHub pages:

cd docs
  • (If new major release) Update the stable symlink to point to the released version.
  • Check that the output makes sense
  • Run git push to update the public version of the docs on gh-pages.

7. Update the IPython website

  • release announcement (news, announcements)
  • update current version and download links
  • (If major release) update links on the documentation page

8. Drafting a short release announcement

This should include i) highlights and ii) a link to the html version of the What's new section of the documentation.

Post to mailing list, and link from Twitter.

9. Update milestones on GitHub

  • close the milestone you just released
  • open new milestone for (x, y+1), if it doesn't exist already

10. Celebrate!

Something went wrong with that request. Please try again.