You don't have .gem/ruby/2.6.0/bin in your PATH, gem executables will not run
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:
- 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:
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.
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:
/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 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
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
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:
$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
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
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 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.