How do I install Ruby on a Mac with Homebrew and rbenv?

The short version

A version manager is a tool that keeps several Ruby versions on one machine and picks one for you. rbenv is one such tool, and Homebrew is a package manager for the Mac that installs command line programs. The Ruby site's install page lists rbenv among the managers and notes that rbenv cannot install Ruby by itself, so it pairs with the ruby-build plugin. Open Terminal and run these in order:

brew install rbenv ruby-build
rbenv init

Close the Terminal window and open a new one. The rbenv README says to do this so the changes take effect. Then:

rbenv install -l          # lists the latest stable versions
rbenv install 3.3.6       # use a version from that list
rbenv global 3.3.6        # make it your default
ruby -v
# => ruby 3.3.6 (...)
which ruby
# => /Users/you/.rbenv/shims/ruby

The version number 3.3.6 is only an example. Pick one that rbenv install -l shows on your machine. The compile step can take several minutes, and that is normal because ruby-build compiles Ruby from source.

Prefer to check your Mac first? The README tells you to confirm that your build environment has the necessary tools and libraries before running rbenv install. If the build fails, read the error before you retry, and search the message in the ruby-build discussions that the README links.

Why it works

When you type ruby, your shell looks through the folders in your PATH (the ordered list of places it searches for programs) and runs the first match. After rbenv init, the folder ~/.rbenv/shims comes first in that list. According to the README, any call to ruby, gem or bundler then activates rbenv, which looks for a .ruby-version file in your project folder and runs the version named there, or your global version if there is no such file.

That also explains the rbenv local command. Running it inside a project folder writes a .ruby-version file, so that one project can use a different Ruby from the rest of your machine:

cd my-first-project
rbenv local 3.3.6
cat .ruby-version
# => 3.3.6

Which way should I install Ruby?

Option	What you get	Watch out for
The Ruby that came with macOS	Something already on the machine	The Ruby site notes it is included by default, but you do not control its version, and gem installs may ask for sudo
brew install ruby	The newest Ruby, in one command	One Ruby at a time, so switching per project is harder
rbenv with ruby-build	Many versions, one per project if you wish	One extra setup step, and compile time

The Ruby site also lists RVM, chruby and other managers. Any of them is fine; this answer uses rbenv because the steps are short.

Mistakes beginners make

1. Skipping the new Terminal window. The shell reads its startup file when a window opens. Without a fresh window, ruby still points at the old Ruby.
2. Using sudo for gems. The README says you should not use sudo to install gems. If you see a "you don't have write permissions" error, it is likely that your system Ruby is still the global default. Run rbenv global with your version and try again.
3. Installing a version and never selecting it. rbenv install only downloads and compiles. Until you run rbenv global or rbenv local, the system Ruby may still answer.
4. Editing the startup file by hand and getting it wrong. On rbenv 1.3.0 and later, rbenv init edits your shell startup file for you, so a second hand-written copy is rarely needed.

Check this in order

1. Run brew --version. If the command is not found, install Homebrew first from its own website.
2. Run rbenv --version. If it is not found, rerun brew install rbenv ruby-build.
3. Run grep rbenv ~/.zshrc. You should see a line added by rbenv init. (macOS uses zsh by default; if you use bash, look in ~/.bash_profile instead.)
4. Open a new Terminal window and run rbenv versions. An asterisk marks the active version.
5. Run rbenv which ruby to see the exact file rbenv will run.
6. Run ruby -v and which ruby. If the path does not contain .rbenv/shims, go back to step 3.

When ruby -v looks right, start irb and try a line. The guide's Expansion Pak 1 walks through IRB, and What is Ruby? tells you what you installed.

Checked on 12 November 2026.