You don’t have write permissions for the /Library/Ruby/Gems/2.6.0 directory

Did you just try to install a Ruby gem (such as Rails, Jekyll, or cocoapods) on your Mac and got this write permissions error?

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

This is one of the most common errors people face. You’ll get this error for any gem you try to install on a Mac that hasn’t yet been properly configured for Ruby development.

Although Apple preinstalls Ruby on all Macs, this version of Ruby, known as the system Ruby, is not meant to be used for development. If you try to install gems using the system Ruby, the default location where gems would get installed is in the /Library/Ruby/Gems/2.6.0 directory. However, that directory is not meant to be modified, which is why Apple doesn’t give you permissions to write to it.

Although it’s possible to specify a different directory by adding --user-install to the gem install [name of gem] command, I don’t recommend that because you would still be using the system Ruby, and it can lead to one or more of these common issues:

Not being able to use the gems after installing them because they’re missing from the PATH, as mentioned in the warning that gem executables will not run
Gem installation failing with the “failed to build gem native extension” error due to missing or broken dev tools
Not being able to install the latest version of popular gems like Rails, Jekyll, and cocoapods because they require a newer version of Ruby

You might have also been told to install gems with sudo, which overrides Apple’s protection. Please, never use sudo to install gems!

Keep reading to better understand why you shouldn’t use the system Ruby, and a step-by-step guide for what to do instead. If you just want to get your Ruby project working as quickly as possible, here’s a summary of this article:

TL;DR

Managing Ruby on macOS can be painful. Even a working installation can stop working for mysterious reasons, seemingly all by itself.
Fixing a broken installation is tedious and error-prone.
If you want to be up and running in 15 minutes or less, even if you have a broken development setup, buy Ruby on Mac and be done with it. And going forward, you’ll always have a proper and working Ruby dev environment. Join 2100+ happy customers who got unstuck right away. Read 150+ testimonials that show how people feel after buying Ruby on Mac.
If you have a clean Mac, try my free step-by-step guide for installing Ruby on a Mac, which can take an hour to go through and only covers the minimum tools required (Homebrew, chruby, ruby-install).

How to tell if you’re using the system Ruby

To find out whether or not you’re using the system Ruby, run this command:

which ruby

If it says /usr/bin/ruby, then that’s the system Ruby on a Mac, and you definitely don’t want to be using it.

If you already installed a separate version of Ruby with a version manager (like asdf, frum, rbenv, ruby-install, rvm), and which ruby is still pointing to the system Ruby, that means you haven’t properly configured the version manager and/or you haven’t switched to the newer version of Ruby.

In that case, read the instructions for your version manager, or follow my step-by-step guide for installing Ruby on a Mac, or buy Ruby on Mac, which can configure everything for you automatically. The Ultimate version of Ruby on Mac lets you choose your preferred version manager, and you can easily switch from one to another if you want to try different ones.

Why you shouldn’t use the system Ruby on Mac

The system Ruby is old

Monterey (macOS 12) originally shipped with Ruby 2.6.8, and Ventura (macOS 13) and Sonoma (macOS 14) come with Ruby 2.6.10. Both of these versions reached end of life at the end of March 2022. This means all 2.6.x versions have known bugs and security issues that will never be fixed. The latest version of Ruby is currently 3.3.1.

If you try to install the latest version of Rails using the system Ruby, you’ll get an error like this:

ERROR:  Error installing rails:

There are no versions of activesupport (= 7.0.4.3) compatible with your Ruby & RubyGems. 
Maybe try installing an older version of the gem you're looking for?

activesupport requires Ruby version >= 2.7.0. The current ruby version is 2.6.10.210.

activesupport is one of the many gems that Rails depends on. When you install a gem with just gem install [name of gem], it always tries to install the latest possible version of the gem and all of its dependencies. As of today, the latest version of activesupport (and Rails) is 7.0.4.3, which requires Ruby version greater than or equal to 2.7.0. However, as of macOS Ventura, the latest possible version of the system Ruby is 2.6.10.

Therefore, if you want to use the latest version of Rails, which would be the case if you’re creating a brand new Rails app, or if you’re working on an existing Rails 7 app, you can’t use the system Ruby even if it was a good idea to use it.

The system Ruby can’t be updated or upgraded

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

Similarly, it’s not possible to upgrade the system Ruby to a newer version, nor would you want to do that. Instead, you want to install a separate version of Ruby that doesn’t interfere with the system Ruby.

Apple will probably stop preinstalling Ruby on macOS

In the release notes for macOS Catalina, Apple mentioned it won’t include Ruby in future versions of 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.

Since then, Apple released three more macOS versions (Big Sur, Monterey, and Ventura) that came with Ruby, so it’s not clear when that change will happen, but I like to stay ahead of the curve, which is why Ruby on Mac will still work when that happens.

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

As you experienced, simply running gem install while using the system Ruby doesn’t work. It gives you the infamous “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

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.

Although you can install gems using the system Ruby without using sudo, by changing the installation path with the --user-install flag, 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 you might be able to install a particular Ruby version with one tool, but not with another. For example, rvm often fails to install various Ruby versions with this error (the number after -j might change; it refers to the number of cores your Mac has):

Error running '__rvm_make -j12'

If you look up that error on their GitHub page, you’ll see many people offering various solutions, but they don’t work for everyone. And even if they did work, they’re usually not the right way to fix the problem.

Or the installation will appear to succeed, but then you won’t be able to install gems due to OpenSSL issues. 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. That’s another reason why you shouldn’t use the system Ruby.

And if you want to install the latest version of Ruby as soon as it’s released, you usually can’t with most of the popular tools because it requires the maintainers to manually update the list of the available Ruby versions, and sometimes it takes them a few days to make the latest version available. And then you have to remember to manually update the tool to pick up the latest versions.

For example, Ruby 3.2.1 was released on February 8, 2023, but it wasn’t available via asdf or rbenv until February 10. If you tried to install it on the 8th or the 9th, you would have gotten this error:

ruby-build: definition not found: 3.2.1

This can be 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.

With Ruby on Mac (which uses a custom version of ruby-install), 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.

If you’re interested in the technical details that show how a particular version of Ruby was configured, you can run irb, and then run this command:

RbConfig::CONFIG

Explaining the info returned by this command is out of scope for this article, but stay tuned for a detailed comparison of all the Ruby version managers, and the pros and cons of the way they each configure Ruby.

So what’s the proper way to install Ruby on a Mac?

Glad you asked! The most reliable method, and the only one I recommend, is to install a separate and newer version of Ruby using a version manager. If you’re really interested in all the possible options, including ones I don’t recommend (such as installing Ruby with Homebrew), read my definitive guide to installing gems on a Mac.

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.

Over the past twelve 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.

Install Ruby with a version manager

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

Install Homebrew (which will also install the prerequisite Apple command line tools)
Install a Ruby version manager such as chruby and ruby-install (others include asdf, frum, rbenv, and RVM)
Configure the Ruby version manager
Install a specific version of Ruby
Switch to that version of Ruby

You have two options for performing those steps:

Have everything set up for you in 15 minutes or less with a single terminal command
Spend an hour or more setting everything up manually

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

Ruby on Mac is the easiest, fastest, and most reliable way to set up and maintain a proper Ruby dev environment on a Mac. It can automatically fix your outdated or misconfigured development setup in minutes, saving you from having to wipe your computer and reinstall macOS. It also automatically installs all the other development tools you’ll need for Rails, Jekyll, Flutter, React Native, or any other project that depends on Ruby. It will save you 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.

Spend an hour or more setting everything up manually

If you prefer to spend an hour or more doing everything manually, you can follow my free step-by-step guide for installing Ruby on a Mac. The guide works best when you start with a clean development environment.

Depending on how messy your setup is, you might need to spend additional time uninstalling some or all dev tools. In the worst case, you’ll need to spend a few more hours backing up your computer, reformatting the hard drive, and reinstalling macOS.