Managing Ruby versions on macOS Apple Silicon with rbenv

Imagine this common scenario: You need to use a specific Ruby version, so you check which one is currently installed by running:

ruby -v

The output shows:

output ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin23]

Realizing that you need a newer version, you attempt to update Ruby. However, after running the update, you check the version again with ruby -v, only to see the same output as before:

output ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin23]

Why Does This Happen?

This issue occurs because macOS comes with a system version of Ruby pre-installed. This version is managed by the operating system and is located in a system directory, usually /usr/bin. Even if you install a new Ruby version using tools like Homebrew, your terminal may still point to the system’s default Ruby version because it appears earlier in your $PATH.

The $PATH is an environment variable that tells your shell where to look for executable files. If the system Ruby appears first in your $PATH, running ruby -v will return the system version instead of the one you just installed.

To override this, you need to manage Ruby versions using a version manager like rbenv, which can properly set the desired Ruby version as the default.

How to 'fix' this?

To resolve this issue, you can use rbenv, a lightweight tool that allows you to easily install and manage multiple Ruby versions.

What is rbenv?

rbenv is a version management tool for Ruby. It allows you to switch between multiple Ruby versions without needing to mess with your system’s default Ruby installation. With rbenv, you can:

• Install multiple versions of Ruby: Easily install and use any Ruby version;
• Switch between Ruby versions: Set a global default Ruby version or specify a Ruby version for a specific project.
• Simplify your Ruby setup: Avoid issues with conflicting Ruby versions, which is particularly useful if you're working on multiple projects with different Ruby dependencies.

Install rbenv

First, install rbenv using Homebrew:

brew install rbenv

This command also installs ruby-build, a plugin for rbenv that simplifies the process of installing new Ruby versions.

Configure Your Shell

Next, you need to configure your shell to use rbenv by adding the following line to your shell's configuration file:

If you're using Bash, open .bash_profile:

nano .bash_profile

If you're using Zsh (the default on macOS), open .zshrc:

nano .zhrc

At the beginning of the file, add this line:

eval "$(rbenv init -)"

This command sets up your shell to load rbenv automatically, allowing it to manage your Ruby versions seamlessly.

Reload your shell configuration:

For Bash:

source ~/.bash_profile

For Zsh:

source ~/.zshrc

Verify rbenv Installation

To verify that rbenv is installed correctly, run:

type rbenv

This should return a path indicating that rbenv is set up. If it does, you're ready to start managing Ruby versions with rbenv.

Install the Desired Ruby Version

Now, list all available Ruby versions:

rbenv install --list-all

This will display a long list of Ruby versions. Choose the one you need (e.g., 3.3.3) and install it:

rbenv install 3.3.3

This command downloads, compiles, and installs the specified Ruby version on your system.

Set the Ruby Version Globally

To set this newly installed Ruby version as the global default, run:

rbenv global 3.3.3

Verify the Ruby Version

Finally, let's check that the correct Ruby version is now active:

ruby -v

You should see the updated version:

output: ruby 3.3.3p20 (2022-04-12 revision 4491bb740a) [arm64-darwin23]

And that's it! You have successfully updated Ruby on your macOS system using rbenv. Whenever you need to switch to a different Ruby version in the future, simply run rbenv install --list-all to view the available versions and install the one you need.

Additional rbenv Tips

• Local Versions: If you need a different Ruby version for a specific project, you can set a local Ruby version by navigating to the project directory and running:

rbenv local 2.7.6

This will create a .ruby-version file in the project directory that tells rbenv to use the specified version of Ruby whenever you're working in that directory.

• Rehashing: After installing a new Ruby version or a gem with executables, run:

rbenv rehash

This updates rbenv's shims, making the new commands available in your shell.

• Uninstalling Ruby Versions: If you ever need to remove a Ruby version, simply run:

rbenv uninstall 2.6.10

With rbenv, managing multiple Ruby versions becomes simple and straightforward, making it an essential tool for any Ruby developer!