You don't have .gem/ruby/2.6.0/bin in your PATH, gem executables will not run

Published by Moncef Belyamani on

Did you just try to install a Ruby gem on your Mac with gem install [name of gem] --user-install, and then got the “gem executables will not run” warning below?

WARNING: You don't have /Users/[your username]/.gem/ruby/2.6.0/bin in your PATH, gem executables will not run.

If you’re like most people who are new to Ruby, you probably first tried to install the gem with the plain gem install [name of gem] command. But then it failed with the you don’t have write permissions for the /Library/Ruby/Gems/2.6.0 directory error.

So then you looked up that error, and you probably came across one or more of these solutions:

  • Add sudo before the gem install command
  • Add --user-install after the gem install command
  • Install Ruby with Homebrew
  • Install Ruby with a version manager (asdf, chruby, frum, rbenv, ruby-install, rvm)

The only solution I recommend is to install a separate version of Ruby with a version manager because it’s the most reliable and least likely to cause issues in the future.

The first two solutions imply that you’re using the version of Ruby that came preinstalled on your Mac, known as the system Ruby. And you should avoid using the system Ruby at all costs!

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. To understand why, read these 5 reasons why you shouldn’t use the system Ruby.

As for sudo, even if you’re not using the system Ruby, please never use sudo to install gems! In general, be wary of solutions that don’t come with a reasonable explanation.

As for the --user-install option, that tells the computer to install gems in a directory that you have permissions to write to: ~/.gem/ruby/2.6.0/bin, as opposed to the default /Library/Ruby/Gems/2.6.0 directory that Apple doesn’t allow you to modify.

As a side note, if you’re not familiar with the ~, it’s a shortcut for your Home folder on a Mac. Instead of typing /Users/[your macOS username], you can replace it with ~.

To understand why it’s warning you that ~/.gem/ruby/2.6.0/bin is not in your PATH, you need to understand what PATH is and how it works.

PATH is an environment variable that contains a list of locations where the computer can find programs to run. The computer looks in each location in order of appearance until it finds the program (or not). You can view this list by running echo $PATH in your terminal.

You should see several directories separated by a space or a colon. For example:

/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin

or

/opt/homebrew/bin /opt/homebrew/sbin /usr/local/bin /System/Cryptexes/App/usr/bin /usr/bin /bin /usr/sbin /sbin

On a brand new Mac, the PATH already includes certain directories, which is why you can run ruby -v and get an answer, because the system Ruby is in /usr/bin/ruby.

And since /usr/bin is included in the PATH, any program inside the /usr/bin directory will be recognized, without having to specify the full name of the location. You can just type the name of the program, and as long as it’s in the PATH, your computer knows what you’re asking for. For example, ruby instead of /usr/bin/ruby.

However, if you install executable programs (like gems) inside a directory that isn’t included by default in the PATH, such as ~/.gem/ruby/2.6.0/bin, then your Mac won’t find them unless you add this new location to your PATH.

What’s more confusing is when the same gem, but perhaps an older or non-functioning version, is installed in a location included in the PATH, and your Mac uses that instead of the newer one you want. For example, Apple comes with the rails command in /usr/bin for some reason, but if you try to use it, you’ll get the common Rails is not currently installed on this system error.

You can temporarily update the PATH by running this command in your terminal:

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

The $PATH at the end represents the current list of directories that the shell knows about. $HOME represents your Home folder, like ~, but it’s usually more reliable to use $HOME in shell scripts.

So what this does is it adds $HOME/.gem/ruby/2.6.0/bin to the existing list, and puts it at the beginning of the list so that the computer looks there first. That way, if the same gem is installed in multiple locations, it will pick the one in ~/.gem/ruby/2.6.0/bin.

After running the export command above, you should now see the new location at the beginning when you run echo $PATH. However, if you quit and restart your terminal, or open a new tab to start a new session, the PATH will revert to its previous value.

To find out how to automatically update the PATH each time you start a new terminal session, read my guide about how PATH works. Having said that, I don’t recommend that you install gems with --user-install, and I don’t recommend you add ~/.gem/ruby/2.6.0/bin to your PATH. Instead, read the rest of this guide for the best way to install Ruby on a Mac.

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.