Stack Update Policy

Last updated 12 September 2017

This document describes Heroku’s policies for when and how we update existing stacks and our schedule for introducing new stacks.

The default Heroku stack is Heroku-16.

Updates to existing stacks

Heroku will update the libraries and other dependencies on currently available stacks from time to time. We generally schedule routine updates quarterly, but updates may also be prompted by security issues or other problems reported with the libraries that are on the stack image. For example, the Cedar-10 stack was updated on May 10th 2013 to pull in security fixes for Ubuntu 10.04.

When making updates to stacks, Heroku strives to to make the updated stack binary-compatible with the current stack and generally try to make as few changes as possible over the lifetime of a stack. This is to maximize stability and continuity for apps running on Heroku.

Before rolling out an update to a stack image, we extensively test it with internal apps. Then we gradually roll out the update on the platform. Any apps encountering problems can be temporarily moved back to the old stack until issues are resolved.

Updates to existing stacks are not reflected in stack version numbers. In general, if we think a stack update may affect running applications, we’ll publish a changelog entry and notify owners of apps that may be affected.

How often does Heroku introduce new stacks?

Heroku stacks are currently based on Ubuntu Linux from Canonical. We strive to introduce updated stack versions as Ubuntu Long Term Support (LTS) versions are released, i.e. every two years. Heroku stack releases will generally trail the Ubuntu release by some months to ensure that packages have stabilized and to give Heroku time to build and test the new stack.

Old stacks are retired when they are no longer receiving support from Canonical (5 years after Canonical introduces that LTS release). Heroku will notify users with apps on old stacks before they are retired. Notifications are in the form of Changelog entries and direct emails to owners and collaborators on apps running on stacks that are about to be retired.

How new stacks are introduced

Several stacks can exists side-by-side on Heroku. When a new stack is introduced, you can upgrade using the stack:set command. Newly created apps use the newest stable stack by default, but you can override this by using the --stack argument when creating apps.

Before a new stack is introduced, Heroku will update the buildpacks that we maintain so that they can create slugs that work on the new stack. Before and after launch, we also work with 3rd party buildpack maintainers to help them make their buildpacks work on new stacks. For information on how buildpacks should handle multiple stacks, see the Buildpack API article.