Setup Rails using chruby and ruby-install

Note: Check the updated version of this post: Installing Ruby using chruby and ruby-install.

Here are the steps to install and set up Ruby and Ruby on Rails on macOS using chruby and ruby-install. Both are very light tools written by Hal Brodigan. A similar approach can also be used on Linux or Windows/WSL.

Setup

Let’s start by installing Homebrew. Follow the official installation instructions on their website.

With that in place, we can now get chruby and ruby-install.

brew install chruby
brew install ruby-install

In order for chruby to work properly, add the following lines to your ~/.zshrc file.

source "$(brew --prefix)/opt/chruby/share/chruby/chruby.sh"
source "$(brew --prefix)/opt/chruby/share/chruby/auto.sh"

Using $(brew --prefix) keeps this working on both Apple Silicon (/opt/homebrew) and Intel (/usr/local).

Using ruby-install

In short, ruby-install is an easy way to install many different flavors of Ruby that are out there: Ruby, JRuby, Rubinius, TruffleRuby (native / GraalVM), or mruby. To get the current stable version of the original Ruby distribution (MRI), just run the following command.

ruby-install --update ruby

And to install a specific version (example):

ruby-install ruby 3.3.6

You might need to run source ~/.zshrc to make it visible to chruby without restarting your terminal session. For more information and other options, refer to the README.

Using chruby

Now that we have different versions of Ruby installed, here is where the magic lives! chruby is a very simple yet powerful tool, written in about 100 lines of code, and it can automatically switch between Ruby versions depending on the folder you’re in.

To list the installed versions, just run:

$ chruby
   ruby-3.2.4
 * ruby-3.3.6

Note that the current version of Ruby has a * next to it. To switch to a different version, just run:

chruby ruby-3.2.4

Be aware that chruby will NOT list the version that comes with macOS. To switch to it, we can run:

chruby system

Switching automatically

If we enter a folder that contains a file named .ruby-version, chruby will automatically switch our current version to the one specified inside that file. If we want to change the default version, we can add it to our home directory, like so.

echo "ruby-3.3.6" > ~/.ruby-version

Installing Rails

Depending on the Rails version and setup you choose, you may also need Node.js and sometimes Yarn (for example, when using JavaScript/CSS tooling that depends on them).

If needed, install them with brew:

brew install node yarn

Now, all we need to do is install Rails via RubyGems.

gem install rails

Verify your setup

Check each command individually and compare with outputs similar to these:

$ ruby -v
ruby 3.3.6p108 (2024-11-05 revision 1234567) [arm64-darwin23]

$ which ruby
/Users/your-user/.rubies/ruby-3.3.6/bin/ruby

$ gem -v
3.5.22

$ rails -v
Rails 7.2.2.1

$ chruby
   ruby-3.2.4
 * ruby-3.3.6

If after installing Rails you don’t see it in your PATH (command not found), try running source ~/.zshrc once more to update your environment.

Note: since the gem is per Ruby installation, it will only be available for the Ruby version that you had selected at that time.