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

Updated

Install Ruby on your Mac with a single command

Have you been struggling for the past few hours, or even days, trying to get your Rails, Jekyll, iOS, Flutter, React Native, or other Ruby project working? Have you been getting error after error when installing Ruby gems, or even just Ruby itself? I have good news for you!

Your Ruby troubles end today.

Over the past twelve years, I’ve helped hundreds of 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 Ruby on Mac product that automates the whole process for you.

If you’re the kind of person that values your time and wants something that just works, give Ruby on Mac a try. You won’t be disappointed. Join 2100+ happy customers who got unstuck right away. Read how much people love Ruby on Mac.

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.

Table of Contents

Prerequisites

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

Once you’ve followed the instructions in this guide to clean up and prepare your Mac, it can take 15 or more minutes to install everything, so if you plan on doing something else while the various tools are installing, temporarily prevent your Mac from sleeping until the installation is done.

Make sure you’re not using a VPN, or a slow shared public WiFi. If you have a mobile hotspot your computer can join, it might be a better option than a public WiFi. You can compare the speeds with a service like fast.com.

Also, make sure you can access this page: https://raw.githubusercontent.com/postmodern/ruby-versions/master/ruby/versions.txt

Some internet and mobile service providers, like ACT in India, are known to block access to certain domains, like the one above from GitHub.

Ruby on Mac uses a workaround to ensure Ruby can be installed even if your ISP is blocking that GitHub domain.

If you’re on Ventura or higher

  1. Click on the Apple icon at the top left of your Mac, and click on System Settings.
  2. Click on “Displays” in the left sidebar
  3. Make the window larger by dragging its bottom edge until you see the “Advanced” button on the right side
  4. Click on the “Advanced” button on the right
  5. In the “Battery & Energy” section at the bottom (you might have to scroll down to see it), make sure to turn on “Prevent automatic sleeping on power adapter when the display is off”
  6. Click “Done”

If you’re on Monterey or earlier

  1. Click on the Apple icon at the top left of your Mac, and click on System Preferences.
  2. Click on “Battery”
  3. Click on “Power Adapter” on the left
  4. Turn on the option to “Prevent your Mac from automatically sleeping 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. In some cases, the warnings might not affect Ruby installation. The rest of the tutorial might still work, but it’s definitely not guaranteed.

If you’re on an Apple Silicon Mac, and your /usr/local folder is not empty, that means you installed Homebrew with Rosetta, or with arch -x86_64 in the terminal, or you transferred your files from an Intel Mac to your Apple Silicon Mac. Regardless of how this happened, it can cause all kinds of issues, and you might run into errors while following this guide, or while installing gems or running bundle install or pod install in your projects.

With Ruby on Mac, you don’t have to worry about fixing Homebrew errors because it automatically detects and fixes common issues when it can. And if they can’t be easily fixed, Ruby on Mac comes with a “reset” mode that will back up then safely clean up your dev environment in 1 minute. Then you can run it in “normal” mode to reinstall everything from scratch in about 15 minutes.

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

Of all the Ruby managers, I recommend chruby because it’s the simplest, and one of the fastest at switching between Rubies. Ruby managers are not compatible with one another, so if you have RVM, rbenv, asdf, or frum, I recommend uninstalling them.

Ruby on Mac Prime will automatically uninstall these other version managers for you if it finds them. With Ruby on Mac Ultimate, it’s even better: you can choose your preferred manager, and update your preference at any time.

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. Look up the uninstallation instructions for each tool on their website/GitHub repo.

If it says “command not found”, then you most likely don’t have it installed. However, it’s possible that it’s still installed, but just not in your PATH. If you’re not familiar with the term PATH, I recommend reading my guide about PATH to learn about it. It will teach you to troubleshoot dev setup issues more confidently.

Make sure you don’t have Ruby installed with Homebrew

This is another thing that Ruby on Mac does automatically for you.

To see which tools are installed with Homebrew, run this command:

brew list

To narrow down the list to only those that contain the string “ruby”, use this command:

brew list | grep ruby

If you don’t see ruby in the list (it might also be listed as ruby@ followed by the version, such as ruby@3.2), that means you don’t have it installed. If you do have it installed, uninstall it like this:

brew uninstall ruby

or for a specific version:

brew uninstall ruby@3.2

Then open ~/.zshrc or ~/.bash_profile (see the Notes on your shell section below), and remove any references to the Homebrew Ruby. Homebrew installs things in either /opt/homebrew or /usr/local. Remove any lines that point to Homebrew directories that also include ruby, for example: /opt/homebrew/opt/ruby.

Make sure you don’t have Cocoapods installed with Homebrew

Another common cause of issues for people using React Native, Flutter, or other projects that depend on Cocoapods, is having multiple installations of Cocoapods. I recommend installing Cocoapods in one way only: with gem install cocoapods once you have a proper Ruby development environment.

Use the same method as the previous section to check if Cocoapods is installed with Homebrew, and uninstall it if it is.

Make sure your macOS username and home folder don’t have spaces in the name

In normal conditions, Apple won’t let you create a macOS username with a space in the name, but I’ve seen it happen in some rare scenarios. Having a space in the Home folder name can cause all kinds of issues in general. To fix this, follow these instructions from Apple very carefully.

Make sure you have enough free disk space

Apple’s standalone Xcode command line tools take up about 5GB of disk space, but the installer might require more than that to be free on your hard drive, probably around 15GB. And in general, it’s best to leave about 10% of your total hard drive size available.

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’re on an Apple Silicon Mac. If it says x86_64, that means Terminal (or whatever terminal app you’re using, such as iTerm) is in Rosetta mode. Here’s how to turn it off:

  1. Quit Terminal/iTerm (or whatever terminal app you’re using) if it’s running
  2. Go to the Finder
  3. Look for your terminal app. For the Apple Terminal app, 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/iTerm/etc
  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 and check uname -m.

If it still says “x86_64”, then you’ll need to completely clean up your dev environment and start over from scratch. A complete cleanup involves about 60 steps that would take an hour to do manually. Or several hours if you were to erase your hard drive and reinstall macOS. Ruby on Mac can safely back up and clean up your dev setup in 1 minute.

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’re 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

Then install the latest Ruby (currently 3.3.0):

ruby-install ruby

It’s important to make sure you can install the latest Ruby before trying to install other Ruby versions.

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.3.0 failed!, or !!! Installation of ruby 3.3.0 failed!, or !!! Configuration of ruby 3.3.0 failed!, or any other error, then there’s most likely something wrong with your development setup.

What to do if Ruby installation fails

The latest Ruby is guaranteed to work when you have a clean development setup. If the latest Ruby fails to install, then you most likely have something in your system that’s interfering with the Ruby installation.

Unfortunately, there are many factors that can affect Ruby installation on Mac, such as:

If you’re installing the latest Ruby, the only solution that is guaranteed to work in all cases is to clean up your dev setup and start over from scratch. This can involve 60 or more steps that can take 60 minutes to complete, so it’s beyond the scope of this tutorial.

It’s definitely possible that there’s a quicker solution, but it would depend on your specific situation. That’s why you might see online people saying that a particular solution worked for them, but someone else is saying nothing so far has worked for them. Also, most of the “solutions” are hacks and workarounds that could lead to other issues.

That’s why I built Ruby on Mac. It’s guaranteed to get you back on track without any hacks. It has a “reset” mode that will safely back up, then clean up your development setup in 1 minute, and then you can reinstall everything from scratch in 15 minutes or less in “normal” mode.

If you’re trying to install an older Ruby version, then it might fail even if you have a clean setup because some older versions require different settings and tools depending on the Ruby version, your Mac model, macOS version, and/or Xcode/Command Line Tools version. For more details, read the section below about installing other Ruby versions.

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

I’ve helped hundreds of thousands of people set up Ruby on their Mac over the past twelve years. First, with this article that I’ve kept up to date, and now with Ruby on Mac. Over 2100 happy customers have saved time and frustration since I released it in February 2022, and will continue to have peace of mind for years to come.

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 how much people love Ruby on Mac.

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.3.0" >> ~/.zshrc

Note that 3.3.0 in the commands above assumes 3.3.0 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 match the version you installed in step 2.

Step 3: Install a gem

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.

Note that some gems are not compatible with Apple Silicon (M1/M2). I recommend replacing them with more modern alternatives, or asking the maintainers if they’re willing to update them. Here are a couple of examples:

Next, make sure to read the rest of this guide. It will save you a lot of confusion and headaches.

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, 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 or higher, 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 3.1.2 -- --enable-shared

Otherwise, if you have CLT/Xcode version less than 14, install Ruby normally without any extra options:

ruby-install 3.1.2

If this sounds complicated, and you don’t want to remember which command to use depending on which Ruby version you want to install, or what kind of Mac you have, you can buy Ruby on Mac Ultimate. It automatically figures out the right settings to use, and all you have to do is run rom install ruby 2.7.8 for example. And if you’re trying to install Ruby 2.6.x on your Mac, or even older Ruby versions on Mac, Ruby on Mac Ultimate will likely be your best option.

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

chruby 3.1.4

chruby is different from other Ruby version managers in that you can’t set a “global” Ruby version that’s automatically available everywhere. If you followed this guide, every time you open a new Terminal window or tab, chruby will switch to Ruby 3.3.0, or the version that appears last in your shell file. Then you should be able to install gems globally within that specific Ruby version with gem install name_of_gem.

However, if you then cd into a different directory that either doesn’t have a .ruby-version file, or if the .ruby-version file is set to a Ruby version that chruby doesn’t know about, chruby will revert to the system Ruby (the one that came with your Mac), which is 2.6.10 on the latest Monterey and higher (Ventura, Sonoma).

You definitely never want to be using the system Ruby! Here are 5 reasons why you shouldn’t use the system Ruby.

You can check by running which ruby. It if says /usr/bin/ruby, that’s the system Ruby, and you don’t want that. If you get errors while trying to install a gem, or running bundle install, the first thing you should check is that you’re using the right version of Ruby.

That’s why I recommend that all Ruby projects have a .ruby-version file that specifies one of the versions that chruby knows about. That way, when you cd into the project, chruby will automatically detect the .ruby-version file and switch to the version defined in the file.

Read the section below to learn how to set up and use the .ruby-version file.

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

  1. Create a test folder and cd into it:

    cd ~
mkdir testing-chruby
cd testing-chruby

  2. Create a file called .ruby-version with 3.1.4 in it:

    echo '3.1.4' >> .ruby-version

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

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

  4. Run ruby -v. It will probably say 2.6.10 (or older), which is the Ruby that came preinstalled on macOS.

  5. cd - to go back to your project. The - is a shortcut to go back to the previous directory in the terminal.

  6. Verify that ruby -v shows 3.1.4

  7. Delete the test folder:

    cd ~
rm -rf testing-chruby

For projects that have a Gemfile, it’s a good idea to specify the Ruby version in your Gemfile, and because it must match the one in the .ruby-version file, you can make that easy by telling the Gemfile to grab the version from the .ruby-version file, by putting this line in your Gemfile, right before the first gem:

ruby File.read(".ruby-version").strip

Here’s an example of what the first few lines of a Gemfile might look like:

source "https://rubygems.org"
git_source(:github) { |repo| "https://github.com/#{repo}.git" }

ruby File.read(".ruby-version").strip

gem "rails", "~> 7.0.4"

Important note about projects with older Ruby versions

If you’re trying to work with an existing Ruby project that has a Gemfile and/or a .ruby-version file that specified a version older than 3.2.3, 3.1.4, 3.0.6, or 2.7.8, you’ll need to either update your app to use a more recent version (best solution), or install the older version specified in your project (not recommended).

This is a very important concept to understand when working with Ruby, and many people waste time trying to install older versions of Ruby when the correct solution is to update the project instead.

For example, it’s not possible to install Ruby 2.7.0 or 2.7.1 on an Apple Silicon Mac (unless you use Rosetta, which I do not recommend). Instead, you should update your project to at least 2.7.8, and then to 3.1.4 because Ruby 2.7 reached end of life in March 2023. Follow the step-by-step instructions in my article that explains how and why to upgrade the Ruby version in your project.

Issues with existing projects

Now that you have a proper Ruby development environment, it won’t necessarily fix issues that are specific to your project. For example, if you’ve been getting errors after running bundle install in an old Ruby project, or when trying to run a Jekyll site with bundle exec jekyll serve, or a Rails app with bin/rails s, those errors could be because the gems and/or Ruby version in your project are outdated.

In the next two sections, I’ll go over how to tell if the issue is specific to your project, and troubleshooting tips.

How to tell if the issue is specific to your project

Check if you can create and run a brand new Rails app, and/or check if you can create and run a brand new Jekyll site.

If you’re able to generate and run a brand new Rails or Jekyll project using the instructions in the links above, then that means you have a working Ruby dev setup, and the issues you’re seeing in your existing project are specific to that project. Read the next section for tips on fixing the issues.

If you’re not able to generate and run a brand new Rails or Jekyll project, then that means something is wrong with your Ruby setup, and you’ll need to start over at the beginning of this tutorial, or buy Ruby on Mac.

How to fix issues in existing projects

The first thing I recommend is to make sure all your gems are up to date. Outdated gems are the most common source of errors.

For example, ffi is a common source of errors on Apple Silicon Macs (M1/M2). If you see ffi anywhere in the error message, it most likely means you’re using a version older than 1.15.2.

In that case, try updating ffi to the latest version:

bundle update ffi

Repeat with any other gems mentioned in error messages.

You might also find this guide helpful: How To Update Gems In Your Gemfile.

Update the Ruby version in your project

I also recommend updating your projects to at least Ruby 2.7.8, and then to 3.1.4 because 2.7.8 reached end of life in March 2023. Here’s a detailed guide I wrote that explains how and why to upgrade the Ruby version in your project.

If you prefer personalized help getting your old Ruby projects running locally (which might involve updating gems and Ruby versions), you can book a 30-minute consultation with me over Zoom. Note that this requires a proper Ruby development environment and that you are able to install these older Ruby versions. If you don’t already have that, the fastest and cheapest way forward is to buy Ruby on Mac Ultimate, which for a limited time includes a free 30-minute consultation.

Note about gems across different Ruby versions

Gems get installed separately in each version of Ruby. For example, if you installed Jekyll and/or Rails in 3.1.4, and then you install Ruby 2.7.8 later, you’ll have to install them again in Ruby 2.7.8.

In the Ultimate version of Ruby on Mac, you can specify which gems you want to be installed automatically whenever you install an additional Ruby version. It’s as simple as adding the name of each gem in a text file called .default-gems.

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.