Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Apps, Dynos and Buildpacks

Stacks and Runtime Versions

Understand Heroku stacks (the operating system image) and language runtime versions, how to pin Node.js, Python, Ruby and Java versions, and how to change stacks safely.

Two version numbers decide what your app actually runs on, and mixing them up causes many confusing errors. The stack is the operating system image your dynos use (a specific Ubuntu version with a set of system libraries). The runtime version is the version of your language: Node.js 22, Python 3.13, Ruby 3.3, Java 21. The stack is chosen per app; the runtime is chosen by files in your repository.

This lesson shows how to read, pin and change both. Specific version numbers move forward every year, so treat the examples as patterns and check the Dev Center for the currently supported list.

Stacks

A stack is named heroku-NN, where NN matches the Ubuntu release it is based on (heroku-24 uses Ubuntu 24.04, heroku-22 uses 22.04). Heroku supports each stack for a limited time and announces end-of-life dates ahead of time. After a stack reaches end of life, new builds on it stop working or lose security updates, so every app needs an eventual migration.

CONSOLE
$ heroku stack
$ heroku stack:set heroku-24
  • heroku stack shows the current stack and the available ones.
  • heroku stack:set changes the stack, but the change only takes effect at the next deploy. It does not rebuild anything by itself, so follow it with a deploy (an empty commit works: git commit --allow-empty -m "Rebuild on new stack", then push).
  • New apps start on the newest default stack.

Because the stack contains system libraries (OpenSSL, image libraries, locale data), a stack upgrade can change behavior even though your code did not change. Test a stack change on a staging app first (see pipelines). The classic gotchas are native extensions that were compiled against old library versions, and strictness changes in the C toolchain.

Runtime versions

Each language buildpack looks for a file or setting that pins the version.

Language Where you pin it Example
Node.js engines.node in package.json "node": "22.x"
Python .python-version (preferred) or runtime.txt 3.13
Ruby ruby line in Gemfile ruby "3.3.5"
Java system.properties java.runtime.version=21
PHP require in composer.json "php": "^8.3"
Go // +heroku goVersion go1.23 in go.mod comment directive

The details differ per buildpack and are updated over time, so check the language-specific article. The principles hold everywhere:

  1. Always pin at least the major (and for Python, minor) version. Without a pin, the buildpack picks a default that moves forward over time, and a deploy months from now may suddenly use a different version.
  2. Prefer ranges that stay in a safe lane, such as 22.x, over wide ranges such as >=18, which can jump a major version without warning.
  3. Match your local version to production so you do not debug differences. Version managers (nvm, pyenv, asdf) read the same files.

Here is a package.json fragment and a Python pin side by side:

JSON
{
  "engines": {
    "node": "22.x",
    "npm": "10.x"
  }
}
TEXT
# .python-version
3.13

Reading build output

The build log tells you which versions were chosen, usually in lines like "Installing Node 22.x" or "Using Python 3.13". Check them after any change. If the line shows a version you did not expect, the pin file is probably missing, misspelled or in the wrong folder (it must be in the repository root for the buildpack to see it).

Stand-in: resolve an engines range

Node's engines.node field accepts semver ranges. This stand-in resolves a few simple range forms against a made-up list of available releases, always choosing the highest match. It does not implement all of semver; it shows why 22.x stays safe while >=18 can drift.

Python Stand-in: pick the highest matching Node version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

>=18 resolves to 24.1.0, a different major version than the one you developed on. 26.x finds nothing, which is how a real build fails when you ask for a version the buildpack does not offer yet.

Stand-in: stack end-of-life checker

Keeping track of which apps run on which stack is an operations chore that scripts handle well. This stand-in uses invented dates to show the logic; look up the real schedule before relying on a date.

Python Stand-in: which apps need a stack upgrade?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A safe upgrade routine

  1. Read the Dev Center changelog and the stack's "what changed" notes.
  2. Create or use a staging copy of the app and set its stack to the new one.
  3. Deploy and run your test suite plus a manual smoke test, watching heroku logs --tail.
  4. If the build fails because of native libraries, pin or upgrade the failing dependency.
  5. Repeat on production during a quiet period, and keep the previous release available for rollback. Note that a rollback does not change the stack back, so be certain before the upgrade.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a Heroku stack?

    A stack is a Linux OS image (for example heroku-24, based on Ubuntu 24.04) with a set of system libraries.
  2. 2. When does heroku stack:set take effect?

    The new stack is used by the next build, so deploy (even an empty commit) after changing it.
  3. 3. Where do you pin the Node.js version for an app?

    The Node.js buildpack reads engines.node from package.json.
  4. 4. Why is a loose range like >=18 risky?

    Open-ended ranges let the buildpack choose the newest release, which can introduce breaking changes between deploys.
  5. 5. Why test a stack change on staging first?

    A new stack updates OpenSSL, compilers and native libraries, which can break native extensions.

Summary

  • The stack is the OS image; the runtime version is your language version. They are set in different places.
  • heroku stack:set applies at the next deploy, and old stacks reach end of life, so plan upgrades.
  • Pin runtimes in repository files (engines, .python-version, Gemfile, system.properties) with safe ranges.
  • Test stack and runtime upgrades on a staging app before production.

Next: Dyno lifecycle and the ephemeral filesystem