Ruby

There is no AI here. All content is human-authored and tested for accuracy.

Change the Ruby Version in a Project

Upgrade a Ruby project to a newer Ruby version. Update files .ruby-version, Gemfile, and Gemfile.lock settings, then run tests and fix issues.

Need to change the Ruby version for a project? This guide shows how to update key files .ruby-version, Gemfile, and Gemfile.lock so your application uses a new Ruby version.

This is a project-level upgrade that may require codebase changes, not just the install of a newer Ruby runtime. If you want to install a newer Ruby on your Mac, see Check Ruby Version and Update Ruby instead. To switch among Ruby versions as you transition and test your codebase, you'll want to Install the Latest Ruby Version and switch Rubies using a version manager. See Choose a Ruby Version Manager for Mac.

Keeping projects running on the current Ruby is part of managing technical debt. Older Ruby versions lose security patches and community support, and gems stop testing against them. Pinning an old version may feel safe, but it makes every future upgrade harder and leaves your application exposed to unpatched vulnerabilities. You can check end-of-life dates for Ruby versions at endoflife.date/ruby to help decide which version to target.

Changing the Ruby version in a project is one step in setting up your Mac for development. See the full roadmap to set up a Mac for software development.

Before you get started

You'll need a terminal application to use Ruby. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it is FREE and worth a try.

Check what Ruby version the project uses now

Before changing anything, find out which Ruby version the project currently requires. Look for these files in the project root directory.

The .ruby-version file

Most Ruby projects include a .ruby-version file. This is the most common way to pin a Ruby version. The file contains a single version number:

$ cat .ruby-version
3.3.0

All major version managers read this file and switch to that version automatically when you enter the project directory. You can verify the active version with ruby -v (see Check Ruby Version).

The Gemfile ruby directive

Some projects specify the Ruby version in the Gemfile. Look for a ruby line near the top:

$ head -5 Gemfile
source "https://rubygems.org"
ruby "3.3.0"

The Gemfile ruby directive tells Bundler to verify the Ruby version at install time. If your active Ruby does not match, bundle install will refuse to run.

The .tool-versions or .mise.toml file

Projects that use asdf or Mise may use a .tool-versions or .mise.toml file instead.

No version file found

If the project has no version file, check the project README or ask the team. For new projects, use the latest Ruby version.

Fix deprecation warnings first

Before upgrading, fix any deprecation warnings on your current Ruby version. Run the test suite and address every warning. This separates deprecation fixes from version-change fixes and makes the upgrade itself much cleaner. If you skip this step, you will be debugging two kinds of problems at once after the upgrade.

Check gem compatibility

Before committing to the upgrade, check whether your key gems support the target Ruby version. Review changelogs or check RubyGems.org for version compatibility notes. If a critical gem does not yet support the new Ruby, you may need to wait or find an alternative. This takes a few minutes and can save hours of debugging a doomed upgrade.

Upgrade the patch version first

If you are planning a major version jump (for example, 3.2 to 4.0), first upgrade to the latest patch of your current version (for example, 3.2.0 to 3.2.6). This picks up bug fixes and additional deprecation warnings that make the major upgrade smoother. Run tests after each patch upgrade.

Install the target Ruby version

Before updating the project files, make sure the new Ruby version is installed on your machine. Use your version manager to install it.

With Mise:

$ mise install [email protected]

With rv:

$ rv ruby install 4.0.2

If you want to install Ruby with Homebrew instead of a version manager, see Install Ruby with Homebrew but note that you won't be able to easily switch among Ruby versions with Homebrew. If you do not have a version manager installed, see Compare Ruby Version Managers to choose one.

Update the project version files

Change every file that specifies the Ruby version. Missing one causes confusing mismatches.

Update .ruby-version

Edit the .ruby-version file to contain the new version number:

$ echo "4.0.2" > .ruby-version

After saving, your version manager will switch to the new version automatically when you re-enter the directory. You may need to close and reopen the terminal or run source ~/.zshrc for the change to take effect, depending on your version manager. Verify with:

$ ruby -v

Update the Gemfile

If the Gemfile contains a ruby directive, update it to match. The simplest approach is to reference the .ruby-version file directly so you only maintain the version number in one place:

ruby file: ".ruby-version"

This syntax (available since Bundler 2.4.19) makes .ruby-version the single source of truth. You update the version in one file and both your version manager and Bundler read it automatically.

If your project uses an older Bundler or you prefer to specify the version explicitly:

ruby "4.0.2"

If your Gemfile uses a flexible constraint such as ruby "~> 3.3", decide whether to tighten it to the exact new version or widen it to allow the new major version.

Update .tool-versions or .mise.toml

If the project uses .tool-versions, update the ruby line:

ruby 4.0.2

If it uses .mise.toml:

[tools]
ruby = "4.0.2"

Update gems and the lockfile

After changing the Ruby version, update the project's dependencies. Old gem versions may not support the new Ruby, and the lockfile records which Ruby was used to resolve dependencies.

First, update Bundler itself to avoid version mismatch problems (see Check Ruby Gems and Bundler for details on Bundler troubleshooting):

$ gem install bundler
$ bundle update --bundler

Then update all gems:

$ bundle update

This resolves all gems fresh against the new Ruby version. Some gems may need newer versions to compile or run on the new Ruby. If a gem fails to build, see the troubleshooting section below and the Ruby Troubleshooting guide for OpenSSL and build-related issues.

Run the test suite

After updating the Ruby version and gems, run the full test suite before committing:

$ bundle exec rake test

Or for Rails apps:

$ bundle exec rails test

Fix any failures before proceeding. Common issues after a Ruby upgrade include deprecated syntax, changed method behavior, and gems that need updating. See What's New in Ruby 4.0 for version-specific compatibility notes.

Smoke-test the running application

Automated tests do not catch everything. For non-Rails projects, run whatever command starts your application and verify basic functionality.

For a Rails application, verify that it boots correctly:

$ bundle exec rails server

Check key endpoints, watch the server logs for errors, and confirm that assets compile. Boot-time errors, configuration mismatches, and runtime behavior changes can slip past the test suite.

Update CI configuration

If your project uses continuous integration (GitHub Actions, CircleCI, or similar), update the Ruby version in your CI configuration file to match the new project version. This ensures tests run against the same Ruby in CI as in development.

Commit the changes on a dedicated branch

Create a separate branch for the Ruby upgrade so it can be reviewed and rolled back independently:

$ git checkout -b upgrade-ruby-4.0.2

Keep the upgrade isolated from unrelated feature work. Mixing business-logic changes with a Ruby upgrade makes debugging much harder if something breaks.

Commit all the changed files together:

  • .ruby-version
  • Gemfile (if it uses ruby file: or a ruby directive)
  • Gemfile.lock
  • .tool-versions or .mise.toml (if used)
  • CI configuration files

Committing these together ensures your team picks up the Ruby upgrade as a single, reviewable change. Open a pull request and deploy to a staging environment before merging to production.

Troubleshoot a project Ruby upgrade

Gems fail to build on the new Ruby

After upgrading Ruby, some gems with native C extensions may fail to compile. This usually means the gem version is too old for the new Ruby. Update the failing gem:

$ bundle update <gem-name>

If the gem is pinned by another dependency (for example, an old version of rubocop), update the parent gem in the Gemfile. See Check Ruby Gems and Bundler for detailed troubleshooting.

Bundler version mismatch

If Bundler installs an old version of itself from the lockfile and crashes, see the Bundler troubleshooting steps in Check Ruby Gems and Bundler.

Tests fail with deprecation warnings

Ruby version upgrades sometimes change default behaviors. Check the release notes for the specific version you are upgrading to. Common changes include keyword argument handling, frozen string behavior, and removed stdlib modules.

Skipping versions

If you are upgrading across multiple major versions (for example, from 2.7 to 4.0), consider upgrading one version at a time. Each step is easier to debug than a large jump, and you can fix deprecation warnings incrementally. The path from 2.7 to 3.0 was the most disruptive recent upgrade. Upgrades from 3.x to 4.0 are generally smoother. See What's New in Ruby 4.0 for version-by-version upgrade notes.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.