Upgrading our Default Heroku Stack for Buildpacks

  • Written by  Peter Baumgartner Peter Baumgartner
  • Published

On May 1, 2024, we will be upgrading our default Heroku Buildpack stack from version 20 (heroku/buildpacks:20) to version 22 (heroku/builder:22). This upgrade will ensure applications continue to receive security updates and transition to Heroku's Cloud Native Buildpacks (CNB) which can improve build speed with better caching and offer better interoperability with standard buildpack tooling.

Known Issues

Heroku has officially flagged the v20 stack as end-of-life, but there are still some edge cases that aren't supported or are backward incompatible.

Community buildpacks are not supported

All of Heroku's officially supported languages will continue to work on v22. Other buildpacks, such as heroku-buildpack-apt have not yet been ported.

If you aren't specifying any buildpacks via app.json or apppack.toml and just letting the builder discover what to use, you shouldn't have anything to worry about here.

No bin/post_compile support in heroku/python

If you have a Python project that has a script at the path bin/post_compile, it will no longer work on the v22 stack. See this blog post for a workaround.

Pinning to v20 stack

If you are unable to upgrade, you can pin your project to the v20 stack using app.json or the preferred apppack.toml. For the latter, make sure it includes the following lines:

[build]
system = "buildpack"
builder = "heroku/buildpacks:20"

You'll also want to disable the EOL warning by setting the following config variable on your app:

apppack -a {yourapp} config set ALLOW_EOL_SHIMMED_BUILDER=1

This is not a long-term fix as the platform is no longer officially supported upstream, but will continue to work for the time being.

Upgrading now

If you wish to upgrade your builder prior to May 1, you can also do so using apppack.toml:

[build]
system = "buildpack"
builder = "heroku/builder:22"

If you are using the builder's auto-discovery feature to determine the buildpack to use (Python, Ruby, etc), that's all you need. If you are manually specifying the buildpacks, however, you'll also need to add the heroku/procfile buildpack to the list. For example, in apppack.toml, if you are using the Node.js and Python buildpacks, it should look like this with the Procfile buildpack:

[build]
system = "buildpack"
builder = "heroku/builder:22"
buildpacks = ["heroku/nodejs", "heroku/python", "heroku/procfile"]

Starting from May 1, 2024, all new builds that don't explicitly define a builder will automatically use the upgraded default Heroku Buildpack stack (version 22).

We are excited about this upgrade and the benefits it brings to our users. If you have any questions or need assistance with the migration process, please don't hesitate to reach out to our support team.