Last updated December 05, 2024

This article describes the Heroku-22 stack, based on Ubuntu 22.04. What is a stack?

What’s new

This stack is now based on Ubuntu 22.04, compared to Ubuntu 20.04 used in the Heroku-20 stack.

The most important changes compared to Heroku-20 are:

• The stack no longer includes a system Ruby installation. This will not affect the vast majority of users, since Ruby apps will use the Ruby installation provided by the Ruby buildpack.
• The stack no longer includes a system Python 2 installation (accessed on Heroku-20 via the python2 command). Python 3 continues to be available via the python and python3 commands, as it was for Heroku-20.

Available software

Every stack on Heroku supports different operating system packages and language runtime versions. This support is typically confined to software that was still actively developed by the respective maintainers at the time the stack was first released.

Language runtimes

For the most accurate information on supported language runtime versions, please check the individual language pages:

Operating system packages

For a full list of operating system packages available on Heroku-22, please refer to article Ubuntu Packages on Heroku Stacks.

Support period

Heroku-22 is based on Ubuntu 22.04. It will be supported through April 2027. Learn more about Heroku’s stack update policy.

Using Heroku-22

You can specify a stack when creating an app:

$ heroku create --stack heroku-22

You may change the stack on an existing app; the next build performed will then use the new stack:

$ heroku stack:set heroku-22

If you are using app.json, you should also specify the stack there to ensure that your Review Apps and Heroku CI runs use the same stack:

{
   "stack": "heroku-22"
}

Upgrading to Heroku-22

Please refer to the stack upgrading guide to understand the procedures to follow when upgrading to a new stack.

Upgrade notes

System Ruby is no longer installed

The stack no longer includes a system Ruby installation. This will not affect the vast majority of users, since by default Ruby apps will use the Ruby installation provided by the Ruby buildpack instead.

If you see ruby: command not found errors, check that you haven’t accidentally been using the system-level Ruby installation; you may do so by verifying the Ruby buildpack is present in your application’s list of buildpacks using heroku buildpacks. If the heroku/ruby buildpack (or a GitHub URL equivalent) is missing, you must add the Ruby buildpack to your app. Run heroku buildpacks:add --index 1 heroku/ruby, create the Gemfile and Gemfile.lock files by running bundle init followed by bundle lock locally, and then deploy the changes.

If after adding the Ruby buildpack, you are still seeing ruby: command not found errors from profile.d/ scripts at application boot, this is due to the fact that profile.d/ scripts are sourced in alphabetical order, and buildpack Ruby is only added to PATH once the profile.d/ruby.sh script runs. Any other profile.d/ scripts will need to have a name that sorts alphabetically after ruby.sh. Alternatively, you can move the contents of any affected profile.d/ scripts to the .profile file instead, which is guaranteed to always run after all other profile.d/* scripts.

If you are a maintainer of a buildpack that uses Ruby, you will need to either:

1. Modify the buildpack so that it vendors Ruby as part of the build (example).
2. Rewrite the Ruby parts of the buildpack to be shell scripts instead.
3. Update the buildpack documentation to say end users should add the Ruby buildpack prior to the buildpack in question (they will also need to ensure minimal Gemfile / Gemfile.lock files exist, so that the Ruby buildpack passes detection).

System Python 2 is no longer installed

The stack no longer includes a system Python 2 installation (accessed on Heroku-20 via the python2 command), since Python 2 has been sunset upstream for some time.

Python 3 continues to be available via the python and python3 commands (either via system Python, or the buildpack provided Python installation), as it was for Heroku-20.

OpenSSL 3

Ubuntu 22.04 ships with OpenSSL 3.0. OpenSSL 1.1 is not available as a runtime library.

If you see OpenSSL/libssl related errors (for example libssl.so.1.1: cannot open shared object file or SSL_read: unexpected eof while reading, but there will be many other variations), you will need to update your dependencies and/or third-party buildpacks to versions that are compatible with OpenSSL 3, and ensure that dependencies or binaries you use are compiled against OpenSSL 3.

In addition, OpenSSL 3 drops default support for a number of legacy/insecure cryptographic algorithms. If you see TLS/SSL related failures connecting from your application to external services, it is likely that those servers are running outdated/insecure software or configurations, that will need to be fixed by the maintainers of those services.

The static buildpack is no longer supported

The experimental heroku-buildpack-static buildpack is not supported on Heroku-22. If your application is using that buildpack (check the output of the heroku buildpacks command for either heroku-community/static or heroku-buildpack-static), you will need to switch to the more modern and regularly maintained Nginx buildpack instead (available via heroku-community/nginx).

For more information, see this migration guide.

Heroku-22 Docker image

Heroku-22 is available as two Docker images:

1. The runtime image (heroku/heroku:22), which is recommended over the build image for most workloads.
2. The build image (heroku/heroku:22-build), which is larger as it includes development headers and toolchains. It is only recommended for customers that need to compile source code or dependencies.

Use the following command in your Dockerfile to use Heroku-22 as your base image:

FROM heroku/heroku:22

To learn more about deploying Docker images, please refer to the Heroku Container Registry and Runtime documentation.