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:
- Add
sudo
before thegem install
command - Add
--user-install
after thegem 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:
- 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.