Ruby

audience developer
level all
topic Ruby
subtopic Installation

Brew Install Ruby

How to install Ruby with Homebrew. Instructions for brew install ruby. Homebrew is an easy way to install Ruby. However, consider alternatives to brew install ruby if you need to switch among Ruby versions.

Before you get started

You'll need a terminal application to install Ruby. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

Steps

Here are the steps for installing Ruby with Homebrew on a Mac.

  1. Check macOS and update macOS.
  2. Install Homebrew.
  3. Install Ruby with brew install ruby.
  4. Update $PATH settings in the ~/.zshrc file.

Alternatives to brew install ruby

Use Homebrew to install Ruby if you are a casual user and won't be using Ruby frequently. For example:

  • you are just learning Ruby;
  • you are building only one project.

Here are drawbacks to installing Ruby with Homebrew:

  • Homebrew may update Ruby to a new version when you upgrade other Homebrew packages.
  • You won't be able to switch between multiple Ruby versions.

Most developers use a software version manager to install Ruby. It will help you manage multiple versions of Ruby. I recommend asdf. Asdf can manage versions of many languages, including Ruby and Node. See instructions, Install Asdf. If you will only develop in Ruby, I recommend Frum, the newest and fastest Ruby version manager. See Install Ruby with Frum.

Automated and assisted installation

If you need just one version of Ruby, use Homebrew (it's easy and free). Or develop your skills and use a software version manager to install Ruby. But if things go wrong, or you want assistance, I recommend Ruby on Mac, a $49 installation script from Moncef Belyamani that installs Ruby using chruby. A $149 premium version gives you a choice of version managers asdf, chruby, frum, rbenv or rvm. Moncef Belyamani is a good guy and provides support if you have Ruby installation problems. He's also written an excellent guide, titled The Fastest and Easiest Way to Install Ruby on a Mac in 2024.

If you need a newer Ruby version

Ruby 3.4.1 is the Ruby latest version (released Dec 25, 2024). As of January 1, 2025, brew install ruby installs Ruby 3.4.1. Check the Homebrew Ruby current version to see if a newer Ruby is installed by Homebrew. To get a newer version than the Homebrew default, use Homebrew to install a version manager and Install Ruby with Frum or Install Ruby with Asdf.

Don't use the Mac system Ruby

MacOS comes with a "system Ruby" pre-installed. MacOS Sonoma includes Ruby 2.6.10 which is not the newest version. It's a bad idea to use the Mac system Ruby. See the article Do not use the MacOS system Ruby. You can see the system Ruby with which ruby and ruby -v.

Leave the system Ruby in place and install the newest Ruby version using Homebrew.

Install Homebrew

Complete the section, Install Homebrew, before you start. Check that Homebrew is installed properly with brew doctor.

$ brew doctor
Your system is ready to brew.

Install Ruby

Use Homebrew to install the default Ruby with brew install ruby. You’ll see diagnostic messages and progress updates.

$ brew install ruby
.
.
.

Check that Homebrew has installed Ruby with brew list.

$ brew list
==> Formulae
ca-certificates	libyaml		openssl@3	readline	ruby

You'll see packages that Homebrew installed previously, plus ruby and four dependencies. Note: At this point, the only way to use the Ruby installed by Homebrew is with a full directory path /opt/homebrew/opt/ruby/bin/ruby because you have not set your shell $PATH environment variable to make Ruby easy to find. Homebrew requires you to explicitly set the $PATH to override the macOS system Ruby.

Configure the shell environment

You'll need to set the $PATH so the Homebrew-installed Ruby takes priority over the macOS system Ruby. Plus you'll need to set the $PATH environment variable to add the directory used for Ruby gems.

Edit either the ~/.zshrc and ~/.zprofile files. See the guide Mac PATH for instructions. Here’s a shortcut to open the file in TextEdit from the Terminal:

$ open -e ~/.zshrc

Mac M1, M2, M3

On Apple silicon, add this at the end of your ~/.zshrc or ~/.zprofile file.

if [ -d "/opt/homebrew/opt/ruby/bin" ]; then
  export PATH=/opt/homebrew/opt/ruby/bin:$PATH
  export PATH=`gem environment gemdir`/bin:$PATH
fi

Save the file. This sets the Homebrew-installed Ruby to a higher priority than the system Ruby and adds the directory used for Ruby gems.

Mac Intel

On Mac Intel, add this at the end of your ~/.zshrc or ~/.zprofile file.

if [ -d "/usr/local/opt/ruby/bin" ]; then
  export PATH=/usr/local/opt/ruby/bin:$PATH
  export PATH=`gem environment gemdir`/bin:$PATH
fi

Save the file. This sets the Homebrew-installed Ruby to a higher priority than the system Ruby and adds the directory used for Ruby gems.

Reset the shell session

Close and reopen the Terminal window to pick up the changes to the configuration file. Or enter source ~/.zshrc or source ~/.zprofile to reset the shell environment without closing the Terminal window.

$ source ~/.zprofile
$ source ~/.zshrc

The source command reads and executes a shell script file, resetting the shell environment.

Confirm Ruby installation

Verify that the Homebrew version of Ruby is installed with ruby -v.

$ ruby -v
ruby 3.4.1

You should see the Homebrew default Ruby version number.

When this was written, Ruby 3.4.1 was the newest version installed by Homebrew.

Troubleshooting

If you need to uninstall Ruby, see the guide Uninstall Ruby.

If you run ruby -v and see Ruby version 2.6.10, it is the system Ruby. Try closing and re-opening the terminal window.

Check the $PATH environment variable.

$ echo $PATH
/opt/homebrew/lib/ruby/gems/3.0.0/bin:/opt/homebrew/opt/ruby/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

On Apple silicon, you'll see /opt/homebrew/. On Mac Intel, you'll see /usr/local/.

You can confirm that Homebrew installed Ruby with brew list.

$ brew list
==> Formulae
ca-certificates  libyaml  [email protected]  readline  ruby

You can see a list of the dependencies installed for Ruby with brew deps --tree --installed.

$ brew deps --tree --installed
ca-certificates

libyaml

[email protected]

readline

ruby
├── libyaml
├── [email protected]
│   └── ca-certificates
└── readline

Pin Ruby

Homebrew may update Ruby to a new version when you upgrade other Homebrew packages. If you don't want Homebrew's Ruby version to be replaced by a newer version, you can use brew pin ruby to prevent updates to Ruby.

$ brew pin ruby

There is no response or result from the command. And there is no diagnostic that indicates that Ruby is pinned. You'll simply see an error message when another Homebrew package tries to update Ruby.

What's next

Optimize the Ruby development environment by updating gems. See the Update Gems section next.

If you want to install Rails (the web application framework), see Install Ruby on Rails.