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

Updated

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 5 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 Ventura (macOS 13.x), Apple’s latest operating system, the version of Ruby that comes preinstalled is 2.6.10. This version reached end of life at the end of March 2022. This means that it has known bugs and security issues that will never be fixed. By contrast, the latest version of Ruby is currently 3.2.2.

The latest versions of popular gems like Rails and Jekyll require at least Ruby version 2.7.0, so even if it was a good idea to use the system Ruby, you wouldn’t be able to install the latest gems with it.

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 the you don’t have write permissions for the /Library/Ruby/Gems/2.6.0 directory 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 system Ruby is missing some libraries

Whether or not you’ll be able to use a particular version of Ruby depends on how it was configured. The way Apple configures Ruby is different from the configuration provided by Ruby installation tools like asdf, frum, rbenv, ruby-install and rvm. And each of those tools configures Ruby a bit differently.

This means that if you install the same version of Ruby using two different tools, such as 3.2.2 with rbenv and 3.2.2 with ruby-install, they won’t necessarily work the same way. For example, even though Ruby 3.2.2 was released on February 8, 2023, it wasn’t possible to install it with asdf or rbenv until February 10. Before then, you would have gotten this error:

ruby-build: definition not found: 3.2.2

This is because it requires the maintainers to manually update the list of the available Ruby versions, and it sometimes takes them days to make the latest version available. And when they add the new version, you still have to remember to manually update ruby-build for the new version to be available on your Mac.

This is a problem because new versions of Ruby can contain fixes for serious security issues, and you want to be able to update your app with the new version as quickly as possible. Learn more in my guide that explains why, when, and how to upgrade the Ruby version in your project.

And out of the box, even 3.2.x will fail to install with asdf on Apple Silicon Macs, and with rbenv on any Mac because the way they configure Ruby is not optimal. You get this error:

Last 10 log lines:
  Check ext/psych/mkmf.log for more details.
*** Fix the problems, then remove these directories and try again if you want.
Generating RDoc documentation
/private/var/folders/s_/k4f3v8rx3m7c0zyjdhzwrvnm0000gn/T/ruby-build.20230209113211.67486.kT3c0w/ruby-3.2.0/lib/yaml.rb:3:
warning: It seems your ruby installation is missing psych (for YAML output).
To eliminate this warning, please install libyaml and reinstall your ruby.
uh-oh! RDoc had a problem:
cannot load such file -- psych

run with --debug for full backtrace
make: *** [rdoc] Error 1

With Ruby on Mac (which uses a custom version of ruby-install to install Ruby), these errors don’t happen because it automatically installs everything you need, it configures Ruby in the best possible way, and you can install the latest version as soon as it’s released, without having to update any tools manually.

Similarly, Apple configures Ruby in a minimal way, and doesn’t link to certain libraries that some gems need. This means there are certain gems you won’t be able to install, or some features might not work.

If you’re interested in the technical details to compare the configuration between different tools and the system Ruby, you can run irb, and then run this command:

RbConfig::CONFIG

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 eleven years, I’ve helped hundreds of 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 and ruby-install.

You have two options for setting up a proper Ruby environment with chruby and ruby-install:

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 1400 happy customers have saved so much time and frustration.

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

See how much people love Ruby on Mac.

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. The guide works best when you’re starting with a clean Mac.