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


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.


Supported macOS versions:

Older macOS versions might still work, but I can’t guarantee it.

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 up to date and happy by running this command:

brew update && brew doctor

It should say Your system is ready to brew at the end.

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, or with the help of Homebrew Discussions. Homebrew usually gives detailed instructions for fixing issues. You can also choose to ignore the errors and warnings. The rest of the tutorial might still work, but it’s definitely not guaranteed.

If you prefer to have a clean system, and you don’t feel like spending time fixing issues, Ruby on Mac comes with a reset mode that will back up then safely clean up your dev environment in 1 minute, and reinstall everything from scratch for you in about 15 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, I recommend uninstalling them. Or at a minimum, deactivate them if you don’t want to completely remove them.

Check if you have other Ruby managers

Run these commands in your terminal:

rvm help
rbenv help
asdf --help
frum versions

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/deactivation instructions for each tool on their website.

Ruby on Mac will automatically uninstall them for you if it finds them.


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’re 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. Click once on the Terminal app to select it, but don’t launch it.
  5. Press the ⌘-i keyboard shortcut to open the Info window (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.
  10. Run arch. It should say arm64.

If either uname -m or arch fail to say arm64, then something else is turning on Rosetta. Check the files below for any mention of arch -x86_64, i386, ARCHFLAGS, or other lines that look like they’re setting the Intel architecture. Then remove them, or comment them out.

Then quit and restart your terminal app.

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"

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

Then install a specific Ruby version, such as 3.1.3:

ruby-install 3.1.3

Note that the latest version is currently 3.2.0, but it’s not yet compatible with certain gems, like Rails, which is why I recommend using 3.1.3 for now. If you know you want the latest version, but don’t know what the version is off the top of your head, you can get it like this:

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.3 failed!, or !!! Installation of ruby 3.1.3 failed!, or !!! Configuration of ruby 3.1.3 failed!, or any other error, it could be due to one of these issues:

If you followed this tutorial exactly as written on a supported macOS version, then an error while installing Ruby is most likely due to something in your development setup. The guaranteed way to fix this is to clean up your dev setup and start over from scratch. This can involve 50 or more steps that can take 60 minutes to complete, so it’s beyond the scope of this tutorial.

The good news is that Ruby on Mac is guaranteed to get you back on track. It can safely back up, then clean up your development setup in 1 minute, and reinstall everything from scratch in 15 minutes or less. Or you can use the comprehensive troubleshooting guide to fix issues one by one.

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. Over 1000 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.

You can also hear customers talk about how much they love Ruby on Mac in these podcast episodes below. The links should take you straight to the part where they start talking about Ruby on Mac.

Configure your shell

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

Note that 3.1.3 in the commands above assumes 3.1.3 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.3 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 the desired version. But first, if you’re on an Apple Silicon Mac (M1 or M2), you need to check which version of the Apple Command Line Tools (CLT) or Xcode you have:

brew config

Look for the lines at the bottom that start with CLT: and Xcode:. If either one of them starts with 14, and you’re trying to install a version older than 3.1.3, 3.0.5, or 2.7.7 (but not 2.6.x or older), then you’ll need to install Ruby like this:

ruby-install 2.7.6 -- --enable-shared

For more details on this issue, read my article about installing Ruby on macOS Monterey and Ventura. And if you’re trying to install Ruby 2.6.x on your Mac, I have another article that goes over your options.

Otherwise, if you’re on an Intel Mac, or an Apple Silicon Mac with CLT/Xcode version less than 14, install Ruby normally without any extra options:

ruby-install 2.7.7

With Ruby on Mac Ultimate, you don’t have to worry about any of this. All you have to do is use the rom CLI, and it will automatically use the best settings. For example:

rom install ruby 2.7.6

To switch to this newly-installed version, quit and restart your terminal, then run chruby followed by the version. For example:

chruby 2.7.7

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.7. 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.7 in it:

    echo 'ruby-2.7.7' >> .ruby-version

    This assumes that you already have 2.7.7 installed. If not, either install it, or replace 2.7.7 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.10 (or older), which is the Ruby that came preinstalled on macOS 13 (Ventura).

  6. cd into your project

  7. Verify that ruby -v shows 2.7.7

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.3, and then you install Ruby 2.7.7 later, you’ll have to install jekyll again in Ruby 2.7.7.

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 might need other tools to work with Jekyll or Rails, such as Postgres, Node, Redis, and Yarn. Ruby on Mac installs and configures 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.