How to Update Ruby on macOS Yosemite with Homebrew

By the end of this page, you will understand how Ruby version management works on macOS, how Homebrew installs and upgrades Ruby, why your terminal may still show an older Ruby version, and how to switch your shell to use the updated Ruby installation correctly.

Ruby on macOS can come from more than one place.

• System Ruby: The version that ships with macOS.
• Homebrew Ruby: A newer Ruby installed by Homebrew.
• Version manager Ruby: Ruby installed by tools such as rbenv or rvm.

The important idea is that installing a newer Ruby does not automatically mean your terminal will use it. Your shell chooses which ruby executable to run based on your PATH.

PATH is an ordered list of directories. When you type ruby -v, your shell searches those directories from left to right and uses the first matching ruby executable it finds.

That means updating Ruby usually involves two parts:

1. Install or upgrade Ruby
2. Make sure your shell points to the correct Ruby first

This matters because many gems require newer Ruby language features, security updates, or newer standard library behavior. In real projects, using the correct Ruby version is essential for:

• installing dependencies successfully
• running Bundler
• matching a team or production environment
• avoiding build and compatibility errors

Think of Ruby installations like having multiple copies of the same tool in different drawers.

• One drawer is the macOS system tools drawer.
• Another drawer is the Homebrew tools drawer.

When you ask for ruby, your terminal checks drawers in a specific order. If it looks in the system drawer first, you keep getting the old Ruby even if a newer one exists in another drawer.

So updating Ruby is not only about putting a new tool in a drawer. It is also about making sure your terminal checks the right drawer first.

Core commands

Update Homebrew itself:

brew update

Upgrade Ruby:

brew upgrade ruby

If Ruby is not currently installed through Homebrew, install it:

brew install ruby

Check which Ruby your shell is using:

which ruby
ruby -v

Check Homebrew's Ruby location:

brew --prefix ruby

Typical PATH setup

After installing Ruby with Homebrew, you often need to add its bin directory to your shell configuration.

Example:

export PATH="$(brew --prefix ruby)/bin:$PATH"

Then reload your shell:

source ~/.bash_profile

On some systems you may use a different shell config file such as ~/.bashrc or ~/.zshrc.

Example workflow

brew update
brew upgrade ruby
which ruby
ruby -v
brew --prefix ruby

If which ruby still points to /usr/bin/ruby, add Homebrew Ruby to your PATH:

export PATH="$(brew --prefix ruby)/bin:$PATH"

Then verify again:

which ruby
ruby -v

What this does

• brew update refreshes Homebrew package data.
• brew upgrade ruby installs the newer Ruby formula version.
• which ruby tells you which executable is actually being run.
• ruby -v shows the active Ruby version.
• updating PATH makes the Homebrew Ruby take priority over the macOS Ruby.

Consider this example:

brew update
brew upgrade ruby
which ruby
ruby -v

Here is what happens step by step:

1. brew update

   • Homebrew downloads the latest package metadata.
   • This lets it know what the newest available Ruby version is.

2. brew upgrade ruby

   • Homebrew upgrades the installed Ruby formula.
   • The newer Ruby files are placed in Homebrew's installation directories.

3. which ruby

   • Your shell prints the path of the Ruby executable it will run.
   • If you see something like /usr/bin/ruby, you are still using macOS system Ruby.
   • If you see a Homebrew path, such as /usr/local/bin/ruby, your shell is using the Homebrew version.

4. ruby -v

   • Ruby prints its version.
   • This confirms whether the active Ruby changed.

If the version did not change, the upgrade may have succeeded but your shell is still using the old executable first.

Example fix:

export PATH="$(brew --prefix ruby)/bin:$PATH"
which ruby
ruby -v

Now the shell checks Homebrew's Ruby directory before the system directories.

Installing gems that require a newer Ruby

Many gems drop support for old Ruby versions. Updating Ruby is often necessary before running:

gem install bundler
bundle install

Running modern Rails applications

Rails projects often specify a minimum Ruby version in Gemfile or .ruby-version. If your Ruby is too old, the app will not boot.

Matching team environments

A project may require a specific Ruby version so every developer runs the same code in development, CI, and production.

Security and maintenance

Older Ruby versions eventually stop receiving updates. Newer versions often include bug fixes, performance improvements, and security patches.

Building native extensions

Some gems compile native code. Those gems may fail on outdated Ruby versions or older toolchains tied to them.

In real projects, developers usually do more than just run brew upgrade ruby.

Common patterns

Verify the active executable

Developers often check both the version and the path:

ruby -v
which ruby

This avoids confusion when multiple Rubies are installed.

Use a project-specific version

Teams often define a Ruby version in files like:

• .ruby-version
• Gemfile

Example:

ruby '3.2.2'

This helps tools and developers stay aligned.

Reinstall gems after a Ruby change

When Ruby changes, some gems may need reinstalling because they were built for a different Ruby version.

Common commands:

gem install bundler
bundle install

Prefer version managers for long-term work

In real codebases, many developers use rbenv or rvm instead of relying only on Homebrew Ruby. That makes switching between project versions easier.

Use guard checks in setup scripts

A setup script may verify Ruby before continuing:

ruby -v
bundle check || bundle install

This is a practical example of validation before running project tasks.

1. Upgrading Ruby but still using system Ruby

Broken assumption:

brew upgrade ruby
ruby -v

If ruby -v still shows the old version, your PATH is likely pointing to /usr/bin/ruby first.

How to avoid it:

which ruby
export PATH="$(brew --prefix ruby)/bin:$PATH"

2. Editing the wrong shell config file

You might add PATH changes to a file your shell does not load.

Examples include:

• ~/.bash_profile
• ~/.bashrc
• ~/.zshrc

How to avoid it:

Check which shell you are using:

echo $SHELL

Then update the correct startup file.

3. Expecting macOS system Ruby to be replaced

Do not try to overwrite /usr/bin/ruby. On macOS, system tools may depend on the system Ruby.

Safer approach:

• install a separate Ruby with Homebrew
• use PATH to select it

4. Forgetting to reload the shell

After changing your shell config, the current terminal session may not see the change.

Fix:

source ~/.bash_profile

Or close and reopen the terminal.

5. Assuming old gems will automatically work

After switching Ruby versions, you may need to reinstall gems.

Example:

gem install bundler
bundle install

6. Mixing Homebrew Ruby with version managers

If you have both Homebrew Ruby and rbenv or rvm, it can become unclear which Ruby is active.

How to avoid it:

• choose one main approach
• check with which ruby
• inspect your shell startup files for conflicting configuration

Homebrew Ruby vs System Ruby vs Version Manager

brew upgrade vs brew install

which ruby vs ruby -v

You usually need both when debugging version issues.

# Update Homebrew package data
brew update

# Install Ruby if needed
brew install ruby

# Upgrade existing Homebrew Ruby
brew upgrade ruby

# See active Ruby path
which ruby

# See active Ruby version
ruby -v

# See Homebrew Ruby install prefix
brew --prefix ruby

PATH fix

export PATH="$(brew --prefix ruby)/bin:$PATH"

Add that line to your shell config file if needed.

Key rules

• Installing Ruby is not the same as using it.
• PATH decides which ruby runs.
• Do not replace macOS system Ruby.
• Use which ruby and ruby -v together.
• Reinstall gems if necessary after changing Ruby.

Common files

• ~/.bash_profile
• ~/.bashrc
• ~/.zshrc

Useful follow-up commands

gem install bundler
bundle install

Why does ruby -v still show the old version after brew upgrade ruby?

Because your shell is probably still finding system Ruby first in PATH.

How do I check which Ruby my terminal is using?

Run:

which ruby

Should I replace the macOS system Ruby?

No. It is safer to leave system Ruby alone and use a separate Homebrew or version-manager installation.

Do I need to reinstall gems after updating Ruby?

Often yes, especially gems with native extensions or project dependencies managed by Bundler.

Is Homebrew enough for Ruby version management?

It is enough if you only need one main Ruby version. If you work on multiple projects with different Ruby versions, rbenv or rvm is usually better.

What shell file should I edit on macOS Yosemite?

It depends on your shell. Check with:

echo $SHELL

Then update the appropriate startup file such as ~/.bash_profile.

What is the difference between installing and upgrading Ruby?

Installing adds Ruby if it is missing. Upgrading updates an existing Homebrew Ruby to a newer version.

• PATH environment variable — Determines which executable runs when multiple versions exist.
• Homebrew — The package manager used to install and upgrade Ruby.
• System vs user-installed software — Explains why macOS tools and Homebrew tools should remain separate.
• rbenv — A Ruby version manager commonly used in development.
• RVM — Another Ruby version manager for switching between Ruby versions.
• Bundler — Manages project gem dependencies and often depends on the correct Ruby version.
• Gems — Ruby packages that may require a minimum Ruby version.
• Shell configuration files — Files such as .bash_profile or .zshrc that set environment variables.