The fastest and easiest way to install Ruby on a Mac in 2022

Updated

Install Ruby on your Mac with a single command

If you’re reading this page, you most likely have been struggling to install Rails, Jekyll, cocoapods, fastlane, compass, bundler, or some other Ruby gem. Or maybe even just Ruby itself. I have good news for you!

Your Ruby troubles end today.

Over the past ten years, I’ve helped thousands of people set up Ruby on their Mac. First, with this free tutorial that I’ve kept up to date over the years, and now, with my popular paid Ruby on Mac script that automates the whole process for you.

Read how much people love Ruby on Mac, and here are more Twitter testimonials.

Your Options

Start here if you choose the long and manual route

Most of the work you’ll be doing in this tutorial will be in the “Terminal” application. The easiest way to open an application in macOS is to search for it via Spotlight.

The default keyboard shortcut for invoking Spotlight is ⌘-Space. Once Spotlight is up, start typing the first few letters of the app you are looking for, and once it appears, select it, and press return to launch it.

Prerequisites

Supported macOS versions:

Older macOS versions might still work, but I can’t guarantee it. Pre-release versions like the Ventura Beta (macOS 13 Beta) are not supported. You most likely won’t be able to install Ruby until Ventura is officially released.

Make sure your computer is plugged in and has a stable internet connection

It can take 15 or more minutes to install everything, so if you plan on doing something else while it runs, temporarily prevent it from sleeping until the installation is done.

You can do that in the Battery -> Power Adapter settings under System Preferences. Turn on the option to “Prevent computer from sleeping automatically when the display is off”.

Make sure your macOS software is up to date

Before you start, make sure you have the latest Apple software updates for your current macOS version. Click on the Apple icon in the top left of your screen, then click on System Preferences, and then click on Software Update. If there are any updates available, install them. If you already have the latest updates for the current macOS version, you don’t have to upgrade to the latest macOS.

Make sure Homebrew is ready to brew

You can skip this section if you know you haven’t tried to install Homebrew yet. If you’re not sure, check the contents of the /usr/local folder by running this command in the Terminal app:

ls /usr/local

If there’s nothing in the folder, then you don’t have Homebrew.

If you’re on a Mac with the Apple Silicon chip (M1/M2), you’ll also need to check the /opt/homebrew folder:

ls /opt/homebrew

If those folders are not empty, that means Homebrew is installed, and you’ll need to make sure that Homebrew is happy by running this command:

brew doctor

It should say Your system is ready to brew.

If it’s not ready to brew, then read what Homebrew has to say and see if you can fix the issues on your own.

If you don’t know how to fix the issues, Ruby on Mac - Prime comes with a reset mode that will back up then safely clean up your dev environment in less than 60 seconds, and reinstall everything for you in minutes.

Make sure you don’t have RVM, rbenv, or asdf installed

Of all the Ruby managers, I recommend chruby because it’s the most stable and easiest to use and maintain. Ruby managers are not compatible with one another, so if you have RVM, rbenv, or asdf, you’ll need to uninstall them.

Check if you have other Ruby managers

Run these commands in your terminal:

rvm help
rbenv help
asdf --help

If those commands return any info, then you have that tool installed. If it says “command not found”, then you don’t have it installed. If you do have it installed, look up the uninstallation instructions for each tool on their website.

The Prime version of Ruby on Mac will automatically uninstall them for you if it finds them.

Installation

Read this part only if you are on an Apple Silicon Mac (M1/M2)

If you’re on an Apple Silicon Mac, make sure Terminal is NOT in Rosetta mode.

You can check by running this command once Terminal opens:

uname -m

It should say arm64 if you are on an Apple Silicon Mac. If it says x86_4, that means Terminal is in Rosetta mode. The only way this could happen is if you changed the setting yourself, most likely after following incorrect or outdated advice. To turn off Rosetta, follow these instructions:

  1. Quit Terminal if it’s running
  2. Go to the Finder
  3. Go to the Utilities folder by pressing shift-command-U (or select “Go” from the menu bar, then select Utilities)
  4. Select Terminal, but don’t launch it. Just click once to select it.
  5. Press command-i (or from the menu bar: “File”, then “Get Info”)
  6. Uncheck the checkbox that says “Open using Rosetta”
  7. Close the Terminal Info window
  8. Launch Terminal
  9. Run uname -m. It should now say arm64 and you can proceed with the rest of this guide.

Notes on your shell

This tutorial assumes you’re using zsh. If you’re not sure, read my guide to find out which shell you are using, and replace any references to .zshrc in the steps below with .bash_profile if you’re using Bash.

All versions of Ruby on Mac automatically detect which shell you’re using and configure it appropriately.

Step 1: Install Homebrew and the Command Line Tools

Homebrew, “the missing package manager for macOS,” allows you to easily install hundreds of open-source tools. The full installation instructions are available in the Homebrew Documentation, but you should only need to run the command that’s listed at the top of the Homebrew site:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Note that the command listed on the Homebrew site could change, so please make sure that what I have listed above is the same. If it isn’t, please let me know and I’ll update it.

Copy and paste the command into your Terminal window, press return, then read what appears in the Terminal, and pay attention to any instructions that require your input. For example, Homebrew will prompt for your macOS password. Note that Terminal does not provide visual feedback when you type your password. Just type it slowly and press return.

Homebrew also automatically installs the Apple Command Line Tools, and it usually installs them in the background, but in case this changes, pay attention if any windows appear that require your input.

Once the installation is successful, quit and restart Terminal, then check if Homebrew is ready to go:

brew doctor

If you get Your system is ready to brew, you can move on to Step 2. Otherwise, read what Homebrew is saying very carefully. They usually provide great instructions that you should follow.

On Apple Silicon Macs, Homebrew might tell you to run a few commands after the installation, such as:

echo "eval $(/opt/homebrew/bin/brew shellenv)" >> ~/.zprofile
eval $(/opt/homebrew/bin/brew shellenv)

Make sure to run those commands.

Quit and restart Terminal, then check if everything is working so far:

brew doctor

Step 2: Install chruby and the latest Ruby with ruby-install

Install chruby and ruby-install:

brew install chruby ruby-install

Install the latest stable version of Ruby:

ruby-install ruby

This will take a few minutes. If it succeeds, go to the next step to configure your shell to automatically use chruby.

If it fails with !!! Compiling Ruby 3.1.2 failed!, or !!! Installation of ruby 3.1.2 failed!, or any other error, that most likely means your development setup is broken. It could also be due to a bug in ruby-install, which is rare, but has happened in the past.

The good news is that Ruby on Mac is guaranteed to get you back on track. I’ve even fixed bugs in tools like ruby-install before they released a new version. So, while everyone else wasted time trying to get things to work, Ruby on Mac customers were up and running in minutes.

Save yourself the headache and your precious time and let Ruby on Mac do all the complicated work for you.

I’ve helped thousands of people set up Ruby on their Mac over the past ten years. First, with this article that I’ve kept up to date, and now with Ruby on Mac. Close to 600 happy customers have saved time and frustration since I released it in February 2022.

Over the years, I’ve heard the same story over and over: people end up wasting hours of their time, and banging their head against a wall, wishing they had found this article and Ruby on Mac earlier. Read their stories, and here are more Twitter testimonials.

Another reason why you might be getting !!! Compiling Ruby 3.1.2 failed! is because you’re using the pre-release version of macOS 13 (Ventura Beta), which is not yet supported by Homebrew (nor by my Ruby on Mac script). If you run brew doctor, you should see this warning:

Warning: You are using macOS 13.
We do not provide support for this pre-release version.
You will encounter build failures with some formulae.
Please create pull requests instead of asking for help on Homebrew's GitHub,
Twitter or any other official channels. You are responsible for resolving
any issues you experience while you are running this pre-release version.

You’ll either need to go back to Monterey (macOS 12) or wait until Homebrew supports Ventura.

Configure your shell

echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.1.2" >> ~/.zshrc

Note that 3.1.2 in the commands above assumes 3.1.2 is the version that was installed at the beginning of Step 2.

Quit and relaunch Terminal, then check that everything is working:

ruby -v

It should say ruby 3.1.2 or later.

Step 3: Install any gem you want

Congrats! You now have a working Ruby development environment. You should now be able to install Rails, Jekyll, cocoapods, fastlane, bundler, compass, or whatever gem you’ve been trying to install for the past few days or months!

Just make sure you don’t use sudo to install any gems!

Now that you have a proper Ruby development environment, you can safely install gems with gem install followed by the name of the gem.

How to install different versions of Ruby and switch between them

To install an additional version, run ruby-install followed by ruby- and the desired version. For example:

ruby-install ruby-2.7.6

You should run chruby followed by the desired version before you start any new project to make sure you’re using the correct version of Ruby.

Another highly-recommended way to automatically switch between versions is to add a .ruby-version file in your Ruby project with the version number prefixed with ruby-, such as ruby-2.7.6. To test that this works:

  1. cd into your Ruby project, such as your Rails app or Jekyll site

  2. First, check to see if the file already exists:

    cat .ruby-version
    

    If not, create it in the next step.

  3. Create a file called .ruby-version with ruby-2.7.6 in it:

    echo 'ruby-2.7.6' >> .ruby-version
    

    This assumes that you already have 2.7.6 installed. If not, either install it, or replace 2.7.6 with a version you already have. You can check which versions are installed by running chruby.

  4. cd into a folder outside of your project, such as your home folder: cd ~

  5. Run ruby -v. It will probably say 2.6.8p62, which is the Ruby that came preinstalled on macOS 12 (Monterey).

  6. cd into your project

  7. Verify that ruby -v shows 2.7.6

Note about gems across different Ruby versions

Gems get installed separately in each version of Ruby. For example, if you installed jekyll in 3.1.2, and then you install Ruby 2.7.6 later, you’ll have to install jekyll again in Ruby 2.7.6.

Whenever installing gems in any version of Ruby, make sure to use gem install followed by the name of the gem. Please never use sudo to install gems.

Next Steps

You now have the bare minimum needed to install gems on a Mac, but you will need other tools to work with Jekyll or Rails. Ruby on Mac installs everything you need to get started right away.

Ruby on Mac can also keep your development environment up to date by simply typing rom. Packages get updated regularly with new features and security fixes, so it’s important to be able to update all tools easily at once.

Knowing when and how to automate is a sign of an effective engineer. Most things you do repeatedly will add up to a lot of wasted time if you don’t find ways to speed them up.

When you buy Ruby on Mac, you’ll have access to the code as well, so you can learn about scripting and automation from it.