Last updated December 16, 2024

Heroku can run Ruby applications across a variety of Ruby implementations and includes support for framework-specific workflows. This document contains version support info.

For general behavior info of Heroku recognizes and executes Ruby applications, see Ruby Behavior in Heroku. For framework-specific tutorials, see:

• Getting Started with Ruby on Heroku tutorial for Cedar-generation apps
• Getting Started with Ruby on Heroku tutorial for Fir-generation apps
• Getting Started with Rails 7 on Heroku
• Getting Started with Rails 7 on Heroku
• Build a Ruby on Rails application image locally in 5 minutes, no Dockerfile required.

Default Ruby Version for New Apps

If your Gemfile doesn’t contain a ruby entry, the current default version is MRI 3.1.6 for Cedar-generation apps and MRI 3.1.3 on Fir-generation apps.

Defaults lock on the Cedar-generation app, but not Fir, until you specify a Ruby version, or the next build that follows Heroku updating the default version . For example, if your app is using a default Ruby version of 3.1.6, you continue to stay on 3.1.6. If Heroku updates the current default version in the future, the next time your app rebuilds and deploys, it uses that new default version.

We highly recommend specifying a Ruby version in your Gemfile and not relying on the default Ruby version. If your application doesn’t have this value in the Gemfile.lock, ensure that the Gemfile has a ruby declaration and then run:

$ bundle update --ruby

The default Ruby version isn’t sticky. We strongly recommend specifying a Ruby version for your application to prevent instability when deploying after a default version change.

Specify a Ruby Version

We install the Ruby version specified in your Gemfile.lock. For example:

RUBY VERSION
   ruby 3.3.5p100

Heroku makes a number of different Ruby implementations available. You can configure your app to select a particular version. See Specifying a Ruby Version for instructions.

We include the version your app uses in your build artifact.

Ruby Version Support Policy

Our Ruby version support follows Ruby Core support policy. We recommend running the latest patch release of a supported Ruby version. We recommend upgrading before a Ruby version reaches end of life (EOL) from Ruby Core.

We recommend only upgrading one version at a time, for example, one Ruby version, or Rails version, or Heroku builder version. This incremental process helps isolate any build or runtime inconsistencies to a single change, so you can isolate and fix the problem faster. On Cloud Native Buildpack apps, you can also debug your Ruby application locally via pack build and Docker

Supported Ruby Versions

Heroku supports the following Ruby versions and the associated Rubygems. A supported version means that you can expect our tools and platform to work with a given version. It also means you can receive technical support. Here are our supported Ruby versions:

Ruby Versions

• 3.1.6, Rubygems: 3.3.27
• 3.2.6, Rubygems: 3.4.19
• 3.3.6, Rubygems: 3.5.16

Unsupported Ruby Versions

The following is a list of deprecated runtime versions present for each stack. The EOL versions are no longer receiving updates from Ruby Core and don’t fall under the Heroku Ruby support policy.

If your version of a library, such as Rails, doesn’t work on a supported Ruby version, you can use a service such as Rails LTS. Rails LTS provides a maintained version of older releases for a fee. The Rails LTS project isn’t affiliated with Heroku or with Rails Core.

Unsupported Versions on Cedar

• On the heroku-20 stack:

  • 2.5.x (EOL): 2.5.7 to 2.5.9
  • 2.6.x (EOL): 2.6.6 to 2.6.9
  • 2.7.x (EOL): 2.7.1 to 2.7.8
  • 3.0.x (EOL): 3.0.0 to 3.0.7
  • 3.1.x: 3.1.0 to 3.1.5
  • 3.2.x: 3.2.0 to 3.2.3
  • 3.3.x: 3.3.0to 3.3.4

• On the heroku-22 stack:

  • 3.1.x: 3.1.0 to 3.1.5
  • 3.2.x: 3.2.0 to 3.2.3
  • 3.3.x: 3.3.0to 3.3.4

• On the heroku-24 stack:

  • 3.1.x: 3.1.0 to 3.1.5
  • 3.2.x: 3.2.0 to 3.2.3
  • 3.3.x: 3.3.0 to 3.3.4

For example, while 2.5.9 is no longer “supported” on the Heroku-20 stack, it’s still available for use at your own risk. Heroku always recommends using a supported Ruby version.

Unsupported Versions on Fir

Any prior Ruby version built with a given builder, for example, heroku-24, is accessible as long as that builder is available. We recommend using these available EOL Ruby versions to incrementally upgrade your application so you can move to a supported version.

Available, but (unsupported,) Ruby versions:

• On the heroku-24 builder:
  • 3.1.x: 3.1.0 to 3.1.5
  • 3.2.x: 3.2.0 to 3.2.3
  • 3.3.x: 3.3.0 to 3.3.4

JRuby Version Configuration

If your application specifies a JRuby engine in the Gemfile.lock,, then a version of the Java Virtual Machine (JVM) installs along with the JRuby version requested. For example:

RUBY VERSION
   ruby 2.6.8p001 (jruby 9.3.6.0)

If your Gemfile.lock has no version specified, the application tries to deploy using a default version of Ruby, not JRuby.

Specifying a JRuby Version

JRuby versions support the multiple Ruby versions listed in the following tables. You must specify one in your Gemfile. JRuby runs on the JVM, which installs alongside JRuby. For a list of supported Java versions and details on how to configure specific versions, see the Java Support article.

For more information on the JVM environment and available JVM options, such as JAVA_TOOL_OPTIONS, see Heroku’s Java Support on Dev Center.

For advanced JDK options, such as using the Zulu JDK or running jmap, you must add the heroku/jvm buildpack as the first buildpack on your app.

JRuby Version Policy

Our support for JRuby follows JRuby core’s version support.

Supported JRuby Versions

JRuby is a Java Virtual Machine (JVM) implementation of the Ruby language that you can deploy to the Heroku platform.

JRuby Versions

• 9.1.17.0, Ruby versions: [2.3.3]
• 9.2.21.0, Ruby versions: [2.5.8]
• 9.3.15.0, Ruby versions: [2.6.8]
• 9.4.8.0, Ruby versions: [3.1.4]

Bundler Version Configuration

The Heroku platform uses a specific set of libraries for managing and running Ruby applications.

Bundler Version Configuration On Cedar

The Ruby buildpack installs a version of Bundler based on the major and minor version listed in the Gemfile.lock under the BUNDLED WITH key:

BUNDLED WITH 1.x installs bundler 1.17.3 BUNDLED WITH 2.0.x to 2.3.x installs bundler 2.3.25 BUNDLED WITH 2.4.x installs bundler 2.4.22 BUNDLED WITH 2.5.x installs bundler 2.5.6

For more information on why we only support specific versions, see Bundler Version. For more information on available settings, see Bundler configuration.

Bundler Version Configuration On Fir

We install the exact Bundler version specified in your Gemfile.lock, as long as it follows this format

BUNDLED WITH
   2.5.6

We execute bundle install to install dependencies. We configure this call via CLI arguments and environment variables.

Default Bundler Version

If your Gemfile.lock doesn’t include the BUNDLED WITH key, we use a default version:

• Cedar-generation apps 1.17.3
• Fir-generation apps 2.4.5

We strongly recommend that you have both a RUBY VERSION and BUNDLED WITH version listed in your Gemfile.lock. If you don’t have those values, you can generate them and commit them to Git:

$ bundle update --ruby
$ git add Gemfile.lock
$ git commit -m "Update Gemfile.lock"

Applications without these values specified in Gemfile.lock can break unexpectedly when the defaults change.

Bundler Version Policy

Bundler Version Policy for Cedar

We support specific versions of Bundler for Cedar apps.

Bundler Version Policy for Fir

For Fir apps, our support for Gemfile.lock formats and bundle install configuration options mirrors Bundler’s maintenance policy. Any Bundler version-specific code remains available for as long as we still support the original builder used.

Supported Bundler Versions

Supported Bundler Versions on Cedar

We only support the specific versions listed in Bundler Version Configuration. For more information on why we only support specific versions, see Bundler Version.

Supported Bundler Versions on Fir

Support for Bundler Versions mirrors the RubyGems’ maintainer’s policies. Application developers are responsible for ensuring any bugs encountered when deploying are not present locally when run with the same bundler commands.

Rails Version Configuration and Support Policy

To specify the Rails version for your application, put it in your Gemfile. See Rails Version Support for more info.

Ruby JIT Support

JIT stands for “Just in Time” compiler. The goal of a JIT implementation is to speed up program execution by providing more efficient code, usually by compiling Ruby code into machine code. Using a JIT increases memory consumption but isn’t guaranteed to make all programs faster. If the JIT implementation you use is not well suited for your app code, JIT can make your application slower.

YJIT

YJIT is more likely to speed up your application. You can enable YJIT on your Ruby application by running:

$ heroku config:set RUBYOPT="--enable-yjit"

Then verify it worked by running:

$ heroku run bash
~ $ irb
irb(main):001:0> puts RubyVM::YJIT.runtime_stats
{:inline_code_size=>488880, :outlined_code_size=>404622}

MJIT

Ruby introduced MJIT in Ruby 2.6 and YJIT in Ruby 3.1. MJIT isn’t recommended as it doesn’t speed up many real world applications. MJIT requires gcc at runtime, which is not available on all Heroku stacks.

Installed Binaries

In addition to the Ruby binary and default tools such as rubygems and bundler packaged with it, some applications need additional binaries to run their applications. Heroku strongly recommends using an explicit buildpack to install such dependencies, but there are some cases where the heroku/ruby buildpack installs additional binaries. This section lists the binaries it installs and when.

If a package.json is at the root of your application and no prior node binary is found on the path, the Ruby buildpack installs a default version of Node.js and NPM. If a yarn.lock file is at the root of your application and no prior yarn binary is found on the path, a version of Yarn installs. “`

Node.js Support

Many Ruby applications use Node ecosystem tools to generate frontend assets. The heroku/ruby buildpack will install a default version of Node to support these applications. However, we highly recommend using the heroku/nodejs buildpack and specifying versions via package.json. For example:

{
  "engines": {
    "node": "20.9.0",
    "yarn": "1.22.19"
  }
}

See Node.js support for more information

Default Node.js and Yarn versions on Cedar

When a Cedar-generation app does not have node binary installed from a previous buildpack such as heroku/nodejs and one or more of the following detection criteria are met, a default version of node and/or yarn will be installed:

• Application has a package.json file in the root directory
• The execjs gem detected from the Gemfile.lock
• The webpacker gem detected from the Gemfile.lock
• A yarn.lock file

When one or more of these detection criteria are met, the heroku/ruby buildpack will install the following defaults:

• Node: 22.11.0
• Yarn: 1.22.22 > warning > We don’t recommend relying on this long-term behavior as the default versions change over time. To control your application’s version of Node or Yarn, you must add the heroku/nodejs buildpack to your project.toml file. And specify the engine versions you depend on in your package.json. See Using Multiple Buildpacks for more info.

Default Node.js and Yarn versions on Fir

When a Fir-generation app contains a package.json at the root of the application it will require the heroku/nodejs-engine buildpack which will install the same default version of node as you would receive from the heroku/nodejs CNB

See Node.js support for more information

Behavior

See the following articles for behavior info:

• Heroku Ruby Behavior
• Ruby Application Behavior on Heroku
• Rack Application Behavior on Heroku
• Rails Application Behavior on Heroku
• Ruby Behavior category

Troubleshooting

See Resolving Debugger Gem Installation Failures or the Troubleshooting Ruby Apps category for help with other issues.

Customer Support

You can submit issues via one of the Heroku Support channels.

Additional Reading

• Specifying a Ruby Version
• Working with Ruby category
• Rails Support category
• Working with Bundler category
• Troubleshooting Ruby Apps category