Last updated April 21, 2021

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

What’s new

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

The python program will now run Python version 3, as Python 2 has reached end-of-life status. Python 2 is still available under the python2 program. Users may also use Python 3 explicitly by invoking python3.

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-20, please refer to article Ubuntu Packages on Heroku Stacks.

Support period

Heroku-20 is based on Ubuntu 20.04. It will be supported through April 2025. Learn more about Heroku’s stack update policy.

Using Heroku-20

Heroku-20 is currently the default stack for newly created apps.

You may also specify it explicitly when creating an app:

$ heroku create --stack heroku-20

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

$ heroku stack:set heroku-20

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-20"
}

Upgrading to Heroku-20

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

Upgrade notes

The python program now points to Python 3

If your application’s code invokes the python program e.g. for scripting purposes during build or at runtime, this will now execute Python 3, so the code you’re running this way must be compatible with Python 3. You may alternatively use the python2 program to temporarily use Python 2, but keep in mind that this version of Python is end-of-life and no longer maintained.

The default OpenSSL configuration now requires use of newer TLS protocols and ciphers

The default Ubuntu 20.04 openssl configuration now sets a minimum TLS protocol version of v1.2. This means that TLS v1.0 and v1.1 are no longer supported by clients using OpenSSL to make outbound requests. This may manifest in the form of OpenSSL “no protocols available” errors if clients hardcode older protocol versions, or if servers do not support TLS v1.2 or higher. For apps using Python, an “[SSL] internal error” error may be shown instead of the “no protocols available” error.

In addition, the default OpenSSL security level (SECLEVEL), was changed from level 1 to level 2. This prevents OpenSSL from using insecure ciphers/keys and may result in “sslv3 alert handshake failure”, “wrong signature type” or “dh key too small” errors when connecting to servers that are running outdated/buggy software, or that have insecure configurations.

If you encounter OpenSSL related errors, first check to see if you can reproduce using curl, in order to rule out issues with third-party clients. For example:

$ heroku run curl -I --ciphers DEFAULT@SECLEVEL=2 <URL>

If the curl command did not reproduce the error, then it’s likely there is a problem with the client/library used to make the connection from your application, such as it hardcoding an old TLS protocol version. Check whether there are newer versions of your application dependencies that fix the issue and if not, report the issue to the author of the library. The following dependencies are known to be incompatible:

• keen Python client prior to v0.7.0 (KeenClient-Python#161)
• postmark Ruby client prior to v1.21.3 (postmark-gem#86)

If the curl command above did reproduce the error, it proves it’s not an issue with the specific client/library being used by your application. Next, try setting the OpenSSL security level back to 1, to confirm whether the default security level change was the cause:

$ heroku run curl -I --ciphers DEFAULT@SECLEVEL=1 <URL>

If this now succeeds, then it likely means the server is running running outdated or misconfigured software that doesn’t perform key/cipher negotiation correctly. Contact the third-party server owner to request that it be fixed.

Datadog buildpack compatibility

If you encounter build errors such as “Package 'libsensors4' has no installation candidate” or “Unable to locate package libsnmp30” and are using the Datadog buildpack, it is likely that your app is pinned to an old Datadog buildpack version, so does not have the compatibility fixes for Heroku-20. See heroku-buildpack-datadog#216 for more details.

Heroku-20 Docker image

Heroku-20 is available as two Docker images:

1. The runtime image (heroku/heroku:20) is recommended for most workloads;
2. The build image (heroku/heroku:20-build) is larger and includes development headers. It is only recommended for customers that need to compile source code.

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

FROM heroku/heroku:20

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