How do you install Ruby on a Mac without breaking things?

To install Ruby on a Mac, use Homebrew with the brew install ruby command, or a version manager such as rbenv, chruby, asdf, mise or RVM if you need several versions. Leave the Ruby that ships with macOS alone, and check the result with ruby -v.

Is Ruby already on your Mac?

Probably. The official Ruby installation page says you can check by typing ruby -v in a terminal, and notes that macOS releases have included Ruby by default since at least El Capitan. That copy belongs to the operating system. It can be old, and installing gems into it with administrator rights mixes your project's needs with the system's.

Which install method should you pick?

The Ruby project lists several routes. Package managers are the easiest. The caveat in the documentation is that the packaged version may not be the newest. Dedicated installers, such as ruby-build and ruby-install, compile a version you choose, including several side by side. Version managers, such as rbenv, chruby, asdf, mise and RVM, help you switch between them. You can also build from source.

A simple rule works for most people. If you run one project and want the current release, use Homebrew. If you maintain several projects that need different Ruby versions, use a version manager plus an installer, so each project can state the version it expects.

How do you install it with Homebrew?

The Ruby page gives the macOS command as brew install ruby, and says it should install the latest Ruby version. Afterward, open a new terminal and run ruby -v. If the output still shows the older system version, your shell is finding the system copy first. Homebrew's own output explains how to put its directory earlier in your path, so follow that message instead of copying a line from a blog.

How do you keep a project on the right version?

With a version manager you record the version in a small file at the project root, and the tool switches when you enter the folder. Check your chosen manager's documentation for the exact file name and setup, because they differ. The point is that a teammate or a build server gets the same Ruby you tested with.

What goes wrong most often?

Three things. First, people install a second Ruby and never fix their path, so the old one keeps answering. Second, they run gem installs with sudo to silence a permissions error, which hides the real cause: the gem directory belongs to the system. Third, they forget that a newly built Ruby needs its gems installed again, so a project that worked yesterday fails with a missing gem today. Running ruby -v and checking which copy responds clears up most of these in a minute.

If a command fails halfway through a compile, read the last lines of the output before retrying. Missing build tools or libraries are the usual cause, and the message normally names them.

What about the security side of installing gems?

Ruby projects pull in many gems, so the install is the start of a supply chain. Commit your lockfile so every machine resolves the same versions. Install gems as your normal user, not with sudo, so a bad gem cannot write to system locations. Review what you add, and scan the dependency list before you ship. Safeguard's free in-browser scan at gold.safeguard.sh/scan checks up to 100 dependencies if you want a quick look at a project.

How to check or apply this

1. Run ruby -v to see what is installed now and where it comes from.
2. Decide: one project or several. One means Homebrew, several means a version manager.
3. Install with the method you chose. For Homebrew, run brew install ruby.
4. Open a new terminal and run ruby -v again to confirm the new version is first.
5. Record the Ruby version in the project so others match it.
6. Install gems without sudo and commit the lockfile.
7. Scan dependencies before release.

Quick check

Sources

• Ruby, Installing Ruby, fetched 18 October 2026.

Last reviewed: 18 October 2026.