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

Published by Moncef Belyamani on
Updated on

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! In general, be wary of solutions that don’t come with a reasonable explanation.

You can trust me because helping people set up and maintain a proper Ruby development environment on their Mac is what I do for a living. Over the past 11 years, I’ve helped hundreds of thousands of people like you. Many of them tell me my articles and products are the best they’ve found by far.

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, give Ruby on Mac a try. And going forward, you’ll always have a proper and working Ruby dev environment. Read how much people love 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) comes 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.2.2.

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 if you install the same version of Ruby using two different tools, such as 3.2.2 with asdf or rbenv (they both use ruby-build to install Ruby), and 3.2.2 with ruby-install, they won’t necessarily work the same way. For example, out of the box, if you try to install Ruby 3.2.x with either asdf or rbenv on an Apple Silicon Mac that doesn’t yet have all the required dev tools, it will fail with an error like this:

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

That’s because the way they configure Ruby is not optimal, and they leave it up to you to manually install the prerequisite tools.

And if you want to install the latest version of Ruby as soon as it’s released, you usually can’t with asdf and rbenv 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.

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 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.

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.

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 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 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 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.

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:

  1. Install Homebrew (which will also install the prerequisite Apple command line tools)
  2. Install a Ruby version manager such as chruby and ruby-install (others include asdf, frum, rbenv, and 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 15 minutes or less with a single 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 a proper Ruby dev environment on a Mac. It also automatically installs all the other development tools you’ll need for Rails, Jekyll, Flutter, React Native, or any other project the 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.

Read more about what makes Ruby on Mac special and how much people love Ruby on Mac.

Spend an hour or more setting everything up manually

If you haven’t yet tried to install Ruby or other development tools on your Mac, you should be able to get up and running with the basics by following my free step-by-step guide for installing Ruby on a Mac.