Why You Shouldn't Use the System Ruby to Install Gems on a Mac

Published

While Macs come preinstalled with Ruby, it’s not recommended to use this version, known as the system Ruby, to install gems.

Here are the 4 main reasons why you shouldn’t use the system Ruby to install gems on macOS, and what to do instead:

The system Ruby is old

On Monterey (macOS 12), Apple’s latest operating system, the version of Ruby that comes preinstalled is 2.6.8. This version will reach end of life at the end of March 2022. This means there won’t be any more updates and security fixes to the 2.6.x series. By contrast, the latest version of Ruby is currently 3.1.1.

The system Ruby can’t be updated

Apple includes Ruby on macOS for compatibility with legacy software. It’s not intended for consumer use, so Apple restricts access to the system Ruby. And when a new version of Ruby comes out, Apple doesn’t update Ruby within the same macOS version.

Apple will likely stop preinstalling Ruby on macOS

In the release notes for macOS Catalina, Apple mentioned it will no longer be preinstalling Ruby on macOS:

Scripting language runtimes such as Python, Ruby, and Perl are included in macOS for compatibility with legacy software. Future versions of macOS won’t include scripting language runtimes by default, and might require you to install additional packages. If your software depends on scripting languages, it’s recommended that you bundle the runtime within the app.

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.

Installing gems doesn’t work out of the box with the system Ruby

Unfortunately, most installation guides for gems make it seem like it’s as simple as running gem install followed by the gem name.

However, on a brand new Mac, installing any gem with gem install will result in this error:

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

That’s because Apple doesn’t want you messing with the system Ruby, so it doesn’t give you permissions to make changes to it.

Unfortunately, you’ll find a lot of bad advice out there to override this protection by using sudo. Learn why you should never use sudo to install gems.

There is a safe way to install gems using the system Ruby, by changing the installation path, but because the system Ruby version is so old, I don’t recommend it. And it’s not guaranteed to work for all gems.

The correct way to install Ruby gems on a Mac

The most reliable method, and the only one I recommend, is to install a separate and newer version of Ruby using a version manager.

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. You will likely come across instructions online to install Ruby directly with Homebrew, but that will eventually confuse you because you can only use one version at a time.

Over the past ten years, I’ve helped thousands of people set up Ruby on their Mac. From clean Macs to the most obscure issues, I’ve seen and fixed it all. And the most reliable solution is to use a version manager, specifically chruby.

You have two options for setting up a proper Ruby environment with chruby:

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

My paid script Ruby on Mac (released in February 2022) will automatically install Ruby with chruby, ruby-install, and all the other development tools you’ll need for Ruby. Over 700 happy customers have saved so much time and frustration.

When you buy Ruby on Mac today, you’ll be supporting an independent developer, and if you need it for your job or business, you should be able to expense it.

Read what people say about Ruby on Mac, and here are more Twitter testimonials.

Spend an hour or more setting everything up manually

Follow my free step-by-step guide for installing Ruby on Mac with chruby and ruby-install. This will only give you the bare minimum setup, which is the manual equivalent of the “Basic” version of Ruby on Mac, minus the comprehensive troubleshooting guide. The guide also works best when you’re starting with a clean Mac.