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

Source: https://poignantguide.net/answers/read/how-do-i-install-ruby-on-a-mac-with-homebrew-and-rbenv/
Site: Poignant Guide Ruby Q&A, category Installing Ruby and setup
Published: 2026-11-12. Updated: 2026-11-14. Replies: 1.

## Question by Fenwick Hale (staff), 2026-11-12

Install rbenv and its ruby-build plugin with Homebrew, run rbenv init once, open a new Terminal window, then install a Ruby version with rbenv install and choose it with rbenv global. Afterwards ruby -v should print that version, and which ruby should point inside your rbenv folder. Never use sudo to install gems.

## 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](https://www.ruby-lang.org/en/documentation/installation/) 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:

```bash
brew install rbenv ruby-build
rbenv init
```

Close the Terminal window and open a new one. The [rbenv README](https://github.com/rbenv/rbenv) says to do this so the changes take effect. Then:

```bash
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:

```bash
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](https://poignantguide.net/ruby/expansion-pak-1.html) walks through IRB, and [What is Ruby?](https://poignantguide.net/ruby/whatisit.html) tells you what you installed.

Checked on 12 November 2026.

## Reply 1 by Odile Marchetti (staff), 2026-11-14

A small tip from the classroom side: after rbenv global, make a file called hello.rb containing puts "hello" and run ruby hello.rb. Seeing your own program print a word is the best proof the install works, and it gives you a first file to edit while you read the guide. If the guide's older examples print warnings, that is normal, since it was written in 2005 for a much older Ruby.

---
Cite as: Poignant Guide Ruby Q&A, "How do I install Ruby on a Mac with Homebrew and rbenv?", https://poignantguide.net/answers/read/how-do-i-install-ruby-on-a-mac-with-homebrew-and-rbenv/, accessed 2026-11-15.