Upgrading Ruby - Steps to follow

Here are the steps you should follow to upgrade Ruby as stress free as possible

Upgrading Ruby sounds scary, and there are plenty of stories about people losing weeks and weeks of work to what feels like relatively small upgrades. In this post, we will talk through some of the steps you should take, and some of the specifics involved in performing a Ruby upgrade.

I will get some self promotion out of the way early. If you’ve been tasked with doing a large upgrade, and even after reading this post you still feel very much out of your depth, get in touch, we can either help coach you through this or take on the work ourselves.

High-level steps to upgrade Ruby

Here are the high-level steps to upgrade Ruby, even if you’ve been doing this a long time, I’d not suggest skipping over any one of them.

Check your current Ruby version

Before upgrading, check the current version of Ruby that you are using by running the command ruby -v. This will give you the current version number. This is important for a future step.

It is good practice to have this version documented somewhere; lots of projects will use .ruby-version (we will talk about this later), but having it in the README is useful to anyone.

Decide on your target version

Determine which version of Ruby you want to upgrade to. You can check the latest stable version of Ruby on the official Ruby releases page.

Our advice is to try and just upgrade to the next stable version of Ruby, there will be fewer headaches, and it is generally easier to turn back. Even if ultimately you want to go up several releases, do it one release at a time.

For example, if you were on Ruby 2.7.8 and wanted to go to Ruby 3.2.2, we would suggest;

  • Ruby 3.0.6
  • Ruby 3.1.4
  • Ruby 3.2.2

If you were on an older point release of Ruby 2.7, such as Ruby 2.7.6, you should upgrade to Ruby 2.7.8 first.

This sounds like extra work, but it will help you in the long run.

Find the differences between your current and desired Ruby version

By using the above releases page, you can check what was changed in a given release. Click on Release notes; here are the release notes for Ruby 3.2.2. From there, you can click on “GitHub releases”, which will take you to a GitHub page detailing the changes. Here we can see lots of bug fixes and some security fixes, there don’t appear to be any breaking changes.

You don’t need to be an expert in the Ruby language after reading these, you just want to get a rough idea about things you may need to test or change once you’ve updated.

Install the new version of Ruby

Use your preferred installation method to install the new version of Ruby. If you use a version manager like rbenv or RVM, you can use their respective commands to install the new version.

We have a section called places to update Ruby which talks about some specifics depending on your setup.

Update Bundler

If you are using Bundler to manage your application dependencies (you should!), update it by running the command gem install bundler. This will ensure that your Gemfile.lock file is updated with the correct gem versions.

bundle install will make sure everything is up to date.

Test your application

After upgrading Ruby and updating your gems, it is essential to test your application to ensure it works as expected. Run your test suite and verify that all tests pass.

Run the application and perform some smoke tests, even if you believe you have adequate test coverage.

Address any issues

If you encounter any issues during testing, investigate and fix them. You may need to update your code or dependencies to be compatible with the new version of Ruby.

By only updating to the next smallest version of Ruby, you should hopefully only be changing a small handful of things at a time.

It is important to re-run your tests and your smoke tests after making these changes. We do not want to change any business logic as a result of our Ruby upgrade.

Commit your changes

Once you have verified that your application works correctly, commit your changes and push them to your version control system. Let it also run whatever builds and tests you have, then you are ready to deploy.

Deploying will very much depend on your individual setup, but we would advise deploying to a staging environment first and making sure everything works as you would expect, and then you’re ready to deploy to production.

Places to update Ruby

On a standard Ruby on Rails app, there are a few common places where you may need to specify your new Ruby version. I will explain each in more detail, but they are

  • Your .ruby-version file
  • Your Gemfile
  • Your build file (e.g. GitHub actions, etc.)
  • Your Dockerfile

What is the .ruby-version file?

.ruby-version is a small text file placed in the root directory of a Ruby project and is recognised by many Ruby version managers, such as rbenv and RVM (RVM is what we use). It is also used by some hosting environments, such as Heroku.

When a Ruby version manager detects the .ruby-version file in a project directory, it sets the specified Ruby version as the default version for that project. This ensures that the project uses the correct version of Ruby and avoids conflicts with other projects or system-wide installations of Ruby.

The .ruby-version file typically contains the version number of Ruby to be used, for example, 3.0.6 or 3.1.4.

If you wanted to update your version of Ruby, you would change this file, and in the terminal move away from the directory and move back in. Your Ruby version manager will see the change and either switch or ask you to install the new version of Ruby.

Changing the Gemfile for a Ruby upgrade

As we cover in “what is a Gemfile” you can also specify your preferred version of Ruby in the Gemfile. To update you would change the version

ruby "3.0.6"

Then re-run bundle install.

Changing your build file for a Ruby upgrade

If you run any automated build or testing along with your project (you should) then you probably have a file that specifies things like what languages you use and how to build the project.

Make sure that any Ruby versions listed in these files get updated.

Here is an example of a Github action which uses Ruby. We could update the ruby-version here. I say “could” because setup-ruby can read your .ruby-version file, meaning you have one less place to upgrade.

uses: ruby/setup-ruby@v1
  ruby-version: '3.2'

Updating Ruby in your Dockerfile for a Ruby upgrade

If you use Docker for local development you will need to upgrade Ruby in your Dockerfile.

Your Dockerfile, much like other build files, will contain what version of languages you need. This will need to be updated to reflect your new Ruby version. It will often be a simple line like below.

FROM ruby:3.2.0

Recent posts View all


Iterate over indexed params in Rails

When your API isn't Rails-shaped, sometimes you need to handle input differently

Web Dev Jekyll

Running Jekyll from inside VS Code

How to set up your VS Code to run Jekyll without needing extra extensions