Heroku Ruby Support
Last updated December 03, 2024
Table of Contents
- Default Ruby Version for New Apps
- Specify a Ruby Version
- Ruby Version Support Policy
- Supported Ruby Versions
- MRI Versions
- Unsupported Ruby Versions
- JRuby Version Configuration
- Specifying a JRuby Version
- JRuby Version Policy
- Supported JRuby Versions
- Bundler Version Configuration
- Default Bundler Version
- Bundler Version Policy
- Supported Bundler Versions
- Rails Version Configuration and Support Policy
- Ruby JIT Support
- Installed Binaries
- Node.js Support
- Behavior
- Troubleshooting
- Customer Support
- Additional Reading
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
Ruby has several different implementations, this one is built from source provided via ruby-lang. It’s also called “ruby/ruby”, “CRuby”, or MRI. We also support the JRuby implementation.
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:
MRI Versions
3.1.6
, Rubygems:3.3.27
3.2.5
, Rubygems:3.4.19
3.3.5
, Rubygems:3.5.16
When a Ruby version reaches end of life, security patches are no longer available. We highly recommend running on a version of Ruby that is actively supported by Ruby core.
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
to2.5.9
- 2.6.x (EOL):
2.6.6
to2.6.9
- 2.7.x (EOL):
2.7.1
to2.7.8
- 3.0.x (EOL):
3.0.0
to3.0.7
- 3.1.x:
3.1.0
to3.1.5
- 3.2.x:
3.2.0
to3.2.3
- 3.3.x:
3.3.0
to3.3.4
- 2.5.x (EOL):
On the
heroku-22
stack:- 3.1.x:
3.1.0
to3.1.5
- 3.2.x:
3.2.0
to3.2.3
- 3.3.x:
3.3.0
to3.3.4
- 3.1.x:
On the
heroku-24
stack:- 3.1.x:
3.1.0
to3.1.5
- 3.2.x:
3.2.0
to3.2.3
- 3.3.x:
3.3.0
to3.3.4
- 3.1.x:
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
to3.1.5
- 3.2.x:
3.2.0
to3.2.3
- 3.3.x:
3.3.0
to3.3.4
- 3.1.x:
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:
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 theGemfile.lock
- The
webpacker
gem detected from theGemfile.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 theheroku/nodejs
buildpack to yourproject.toml
file. And specify the engine versions you depend on in yourpackage.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
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.
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.