Update:
-
I now have a paid script that will set up a proper Ruby environment for you with a single command!
-
I also updated my guide that explains the various ways you can install Ruby gems on a Mac and why I only recommend using a version manager like
chruby
andruby-install
.
You are correct that macOS won’t let you change anything with the Ruby version that comes installed with your Mac. However, it’s possible to install gems like bundler
using a separate version of Ruby that doesn’t interfere with the one provided by Apple.
Using sudo
to install gems, or changing permissions of system files and directories is strongly discouraged, even if you know what you are doing. Can we please stop providing this bad advice? I wrote a detailed article that shows why you should never use sudo to install gems.
The solution involves two main steps:
- Install a separate version of Ruby that does not interfere with the one that came with your Mac.
- Update your
PATH
such that the location of the new Ruby version is first in thePATH
. Some tools do this automatically for you. If you’re not familiar with thePATH
and how it works, it’s one of the basics that you should learn, and you’ll understand why you sometimes get “command not found” errors and how to fix them.
There are several ways to install Ruby on a Mac. The best way that I recommend, and that I wish was more prevalent in the various installation instructions out there, is to use an automated script like Ruby on Mac that will set up a proper Ruby environment for you.
The main reason is that it saves each person a ton of time. Time is our most limited and valuable resource. Why make people do things manually when they can be automated with a perfect result every time?
Another reason is that it drastically reduces the chance of human error, or errors due to incomplete instructions.
If you want to do things manually, keep on reading. First, you will want to install Homebrew, which installs the prerequisite command line tools, and makes it easy to install other necessary tools.
Then, the two easiest ways to install a separate version of Ruby are:
If you would like the flexibility of easily switching between many Ruby versions [RECOMMENDED]
Choose one of these four options:
- chruby and ruby-install – my personal recommendations and the ones that are automatically installed by the Ruby on Mac script. These can be installed with Homebrew:
brew install chruby ruby-install
If you chose chruby
and ruby-install
, you can then install the latest Ruby like this:
ruby-install ruby
Once you’ve installed everything and configured your .zshrc
or .bash_profile
according to the instructions from the tools above, quit and restart Terminal, then switch to the version of Ruby that you want. In the case of chruby
, it would be something like this:
chruby 3.1.0
Whether you need to configure .zshrc
or .bash_profile
depends on which shell you’re using.
If you know for sure you don’t need more than one version of Ruby at the same time (besides the one that came with macOS) [NOT RECOMMENDED]
Even if you think you won’t need another version now, you will eventually and you won’t be able to easily switch. This will cause confusion and headaches, which is why I don’t recommend installing and managing Ruby with Homebrew.
If you choose to use Homebrew to install Ruby despite my warnings, you’ll be on your own if you run into any issues.
- Install ruby with Homebrew:
brew install ruby
Then update your PATH
by running this command:
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/2.7.0/bin:$PATH"' >> ~/.zshrc
The 2.7.0
in the command above assumes Homebrew installed a Ruby version that starts with 2.7
. If you’re using a different version (which you can check with ruby -v
), replace 2.7
with the first two digits of your Ruby version.
Then “refresh” your shell for these changes to take effect:
source ~/.zshrc
Or you can open a new terminal tab, or quit and restart Terminal.
Replace .zshrc
with .bash_profile
if you are using Bash. If you’re not sure, read my guide to find out which shell you’re using.
To check that you’re now using the non-system version of Ruby, you can run the following commands:
which ruby
It should be something other than /usr/bin/ruby
ruby -v
It should be something other than 2.6.3 if you’re on macOS Catalina, or 2.6.8 on Monterey. As of early 2022, 3.1.0 is the latest Ruby version.
Once you have this new version of Ruby installed, you can now install bundler (or any other gem):
gem install bundler