Install Ruby on Mac. The Definitive Guide for 2023.

Updated

When trying to install any Ruby gem on a Mac, people often run into the infamous “you don’t have write permissions error” like this one:

ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory

This can be very frustrating, especially when the proposed solutions are inconsistent, wrong, or potentially dangerous. People face this error mainly due to incomplete documentation.

Most instructions start with gem install followed by the name of the gem, but that doesn’t work out of the box on a new Mac. It results in the error message above. This is the case for any gem you try to install on a Mac that has not yet been properly configured for Ruby development.

macOS returns this error because the default location for Ruby gem installations is the system Ruby directory that is preinstalled by Apple. That directory is not meant to be modified, hence Apple not giving us permissions to write to it.

Here’s a good summary of the main reasons why you shouldn’t use the system Ruby to install gems.

So how can you install gems on a Mac?

There are two main options:

1) Install a separate version of Ruby that you control (recommended)

or

2) Keep using the system Ruby via some modifications (highly discouraged)

Option 1 can be further split into two options:

1) Install the new version with a Ruby version manager (recommended)

or

2) Install the new version with Homebrew (not recommended) 1

I highly recommend using a Ruby version manager because it allows you to have multiple versions of Ruby installed at the same time, and makes it easy to switch between them. Even if you’re using Ruby for the first time, it’s worth your time to learn how to use a Ruby manager because you will inevitably need one as you progress.

Since the version manager option is the one I recommend, I’ll go over it first, and then I’ll describe the other options so you can appreciate how complicated this can get, and why I wrote the Ruby on Mac script that sets up a proper Ruby environment on your Mac in minutes with a single command.

Read what people say about the script.

Table of Contents

This guide covers the four main ways to install Ruby on a Mac:

Install Ruby with a version manager (Best option)

At a high level, there are a minimum of five steps to a working Ruby environment on macOS with a Ruby version manager:

  1. Install Homebrew (which also installs the prerequisite Apple command line tools, also known as the Xcode command line tools)
  2. Install a Ruby version manager (such as chruby, rbenv, asdf, rvm)
  3. Configure the Ruby version manager
  4. Install a specific version of Ruby
  5. Switch to that version of Ruby

You have two options for performing those steps:

Have everything set up for you in minutes with a single command

Ruby on Mac will automatically install Ruby with chruby, ruby-install, and all the other development tools you’ll need for Rails or Jekyll. It will save you so much time and frustration.

It doesn’t just have a one-time use. You can run it over and over to keep your dev tools up to date and secure. And the next time you get a new Mac, it will save you a whole day because it can also automatically install all your Mac apps, fonts, macOS preferences, and GitHub repos, in addition to a complete development environment. You get all of these time savings now and in the future for a one-time cost.

If you’re trying to set up Ruby on a work computer, you should be able to expense the one-time cost of Ruby on Mac.

Read what people say about Ruby on Mac.

Spend an hour or more setting everything up manually

Follow my step-by-step guide for installing Ruby on Mac with chruby and ruby-install. The guide works best when you’re starting with a clean Mac, or when brew doctor says “Your system is ready to brew.”

You’ll then need to manually install all the other necessary tools for Rails or Jekyll. And the next time you get a new Mac (for a new job or for yourself), you’ll waste time again setting everything up manually.

Ideally, every maintainer of a Ruby project would point their users to a script that can set everything up for them. Not only does it save time, but it virtually eliminates errors — and therefore discouragement — at such a critical time for beginners. It also saves the maintainers time thanks to a decrease in issues reported by users.

In Badass: Making Users Awesome, Kathy Sierra makes two very important points:

Working on what stops people matters more than working on what entices them.

and

What’s much much worse than a bad user manual? Making the user think the manual works just fine for everyone else.

Sadly, many projects don’t provide prerequisite setup instructions. If they do, they are typically missing steps.

The biggest reason of all to provide a script, or at a minimum step-by-step instructions for installing Ruby with a manager like chruby and ruby-install, is that Apple will no longer be preinstalling Ruby on macOS2. It’s not yet clear to me when that change will happen, but I like to stay ahead of the curve, which is why my Ruby on Mac script will still work when that happens.

This concludes the recommended way to install Ruby on a Mac. The rest of this article goes over other ways to install Ruby, but just for completeness. I don’t recommend them for long-term happiness.

This is similar to the previous option, but instead of installing a Ruby manager with Homebrew, you can install Ruby directly with Homebrew.

The big difference though, is that you cannot easily switch between different Ruby versions. This is going to cause you confusion and headaches down the road.

Doing this manually involves three steps, followed by relaunching the Terminal:

Step 1: Install Homebrew

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

Step 2: Install a Ruby version

Visit the Homebrew site for all the supported Ruby versions you can install. To install the latest:

brew install ruby

Step 3: Update the PATH environment variable to point to Homebrew’s Ruby installation.

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

Replace .zshrc with .bash_profile if you’re using bash. If you’re not sure, read my guide to find out which shell you’re using.

Also, note that the location of Homebrew’s installation might be different on M1 Macs. Read the instructions that Homebrew printed to your terminal.

Step 4: Relaunch your Terminal (or open a new tab)

To verify that you’re using the Homebrew version of Ruby, run this command:

which ruby

You should see /usr/local/opt/ruby/bin/ruby, or /opt/homebrew/opt/ruby/bin on M1 Macs.

If you don’t, the two most likely reasons are that you didn’t relaunch the Terminal, or the PATH is not set properly. See step 3 above. A misconfigured PATH is a common source of confusion and errors. There are plenty of instructions on the internet for setting the PATH, but very few explain what PATH does and why it needs to be updated. Read my guide about PATH to learn more.

Now you can run gem install rails successfully. But wait! What happens if you try to use Rails? If you try rails -v for example, you’ll get this error:

Rails is not currently installed on this system. To get the latest version,
simply type:

    $ sudo gem install rails

You can then rerun your "rails" command.

What do you mean it’s not installed? I can see it when I run gem list! In some cases, this could be due to not relaunching the Terminal (or opening a new tab). In this case though, it’s because Homebrew installs gems in a particular directory that needs to be added to the PATH.

But how did macOS recognize the rails command to begin with? That’s because there is a rails command in /usr/bin that Apple preinstalls for some reason. That message with the shocking suggestion to use sudo comes from Apple, not Rails.

Other gems that don’t already exist in /usr/bin will also fail to be found after being installed, but with a different message:

$ gem install jekyll
$ jekyll -v

zsh: command not found: jekyll

If you paid attention when you ran brew install ruby, you might have noticed a message like this one:

By default, binaries installed by gem will be placed into:
  /usr/local/lib/ruby/gems/3.1.0/bin

You may want to add this to your PATH.

So, in order to be able to install gems and use them with a Homebrew Ruby installation, your PATH needs to include the location of the Homebrew Ruby, as well as the gems location:

export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.1.0/bin:$PATH"

The 3.1.0 above assumes Homebrew installed a Ruby version that starts with 3.1. If you’re using a different version (which you can check with ruby -v), replace 3.1 with the first two digits of your Ruby version.

Also note that the PATH might be different on M1 Macs. You’ll typically need to replace /usr/local with /opt/homebrew. The best thing to do is to follow Homebrew’s instructions.

The downside to installing Ruby with Homebrew is that you can only use one version of Ruby at a time. And you’re also limited to specific versions available on Homebrew. Once you start working on multiple projects, each with its own supported version of Ruby, this can quickly cause problems.

While Apple doesn’t grant you write access to the system Ruby directory, RubyGems does provide a way to specify an alternative location for gem installations. You can do that in one of two ways:

gem install rails --user-install

gem: --user-install

In addition, to use the gems, you need to update the PATH in your ~/.zshrc or ~/.bash_profile:

export GEM_HOME="$HOME/.gem"
export PATH="$HOME/.gem/ruby/2.6.0/bin:$PATH"

The 2.6.0 above assumes you are on Catalina or later. For previous macOS versions, replace 2.6 with the first two digits of your system Ruby, which you can find by running ruby -v.

While this option will allow you to run gem install without getting permission errors, it won’t guarantee that all gems will be able to install successfully. A typical error in this scenario looks something like this:

ERROR: Failed to build gem native extension

That’s because some gems require certain developer tools that don’t come preinstalled on macOS. Apple provides these tools as part of the Xcode app, but also as a standalone package called the Command Line Tools (CLT). The most recommended way to install the CLT is with this command:

xcode-select --install

Unfortunately, this doesn’t always work. Sometimes, macOS displays this error:

Can't install the software because it is not currently available from the
Software Update server.

What does seem to work consistently is to install Homebrew, which detects whether or not the CLT are installed, and if not, it uses a different and more reliable command to fetch and install them.

Once Homebrew is installed, you should be able to install gems using the system Ruby. The downside to this option is similar to the one above in that you can only use one version of Ruby, but it’s even worse because you are stuck with the version that came with macOS, and you can’t upgrade it until a new major version of macOS comes out, once a year on average.

But as mentioned above, Apple is no longer planning on preinstalling Ruby in future versions of macOS. As of today, the latest version you could possibly get from Apple is 2.6.10 via Ventura (macOS 13), while the current latest stable release is 3.2.1.

Here’s a good summary of the main reasons why you shouldn’t use the system Ruby to install gems.

Keep using the system Ruby by overriding Apple’s protection (Never do this!)

This involves elevating your privileges by using sudo, such as:

sudo gem install some_gem_you_should_not_install

Unfortunately, this is a common solution offered on the internet, either out of laziness, or unfamiliarity with better options. Learn why you should never use sudo to install gems.

In addition, prefixing the gem install command with sudo on its own will not install all gems successfully on a Mac that doesn’t have the command line tools installed.

It’s never as simple as it seems, which is why I wrote the proven and reliable Ruby on Mac script that can set everything up safely in minutes.

  1. Virtual machines, containers, and cloud services are other options, but in this post, I’m only focusing on installing directly on macOS. ↩

  2. Look for the “Scripting Language Runtimes” section. ↩