Ruby

There is no AI here. All content is human-authored and tested for accuracy.

macOS System Ruby

You may have heard, "Don't use the Mac system Ruby." It is good advice, but why?

The Mac system Ruby exists for Apple’s legacy compatibility needs, not for you to use for software development. It's okay to use it to run simple scripts, but stop! don't install any gems (Ruby software libraries) using the Mac system Ruby. For developing software with Ruby, you should Install Ruby with Homebrew or use a version manager such as Mise or rv.

Understanding the system Ruby is one step in setting up your Mac for development. See the full roadmap to set up a Mac for software development.

Before you get started

You'll need a terminal application to check which Ruby you are using. 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 is FREE and worth a try.

Are you running the Mac system Ruby?

MacOS comes with a "system Ruby" pre-installed.

To find out what version of Ruby is installed on macOS, Open a Terminal Application and check:

$ ruby -v

Don't type the $ character. The $ character is just a cue that you should enter a shell command. If you enter it, you'll get the error Command not found: $.

If your shell defaults to the system Ruby, the ruby -v command will show a response like:

$ ruby -v
ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin25]

If you see Ruby version 2.6.10, it is the system Ruby. You'll need to install the Latest Ruby Version.

You could see zsh: command not found: ruby but that is unusual, as it can only happen if someone uninstalled the macOS system Ruby.

Use the which command to check if the shell is finding the Ruby runtime:

$ which ruby
/usr/bin/ruby

If you see /usr/bin/ruby, it is the pre-installed macOS system Ruby. For a more detailed walkthrough of checking your Ruby environment, see Check Ruby Version on Mac.

Some developers use the system Ruby for running sysadmin scripts. That is fine, as long as you don't alter the system Ruby by attempting to update or add gems.

For developing projects with Ruby, you should Install Ruby with Homebrew or use a version manager such as Mise or rv. A version manager helps if you are working on multiple projects and need to switch among Ruby versions. For a guide that compares version managers and shows the best way to install Ruby, see Choose a Ruby Version Manager for Mac.

Why using the macOS system Ruby is bad

Here are reasons why it is a bad idea to use the Mac default Ruby for development.

Gem installation problems

RubyGems are the ready-made software libraries that make development easy and powerful in Ruby. Most Ruby projects use at least a few gems.

If you use the Mac system Ruby, running gem install will try to save gems to the system Ruby directory /Library/Ruby/Gems/2.6.0. That directory is owned by root, the system superuser. Ordinary users are not allowed to write to it (and you really should not alter this folder). For help managing gems after installing a proper Ruby, see Check Ruby Gems and Bundler.

If you try to install a gem, for example, gem install rails, you will get a permissions error:

ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory

Don't violate system security

Unix-based systems are powerful, so there is a workaround. You can install gems as a superuser to override the permissions restriction. But don't do this!

$ sudo gem install rails

Any time you are about to run sudo, you should stop and ask if you are about to shoot yourself in the foot.

In this case, you need sudo because you are altering system files that are managed by the OS. Don't do it! You may leave the system in a broken or compromised state. Even worse, a gem might contain malicious code that tampers with your computer.

Gem management

Even if you are willing to take a risk with your system security, you will end up with a folder of (sometimes incompatible) gems that can be confusing to manage. Imagine if you have projects that use different versions of a gem (maybe there was a new gem release between your projects). Or maybe two different gems in your project rely on different versions of a dependent gem. Which gem version is installed in your system gems folder? Which does your project need to use?

Ruby developers use Bundler to manage gems.

Bundler installs gems and their dependencies. It also manages which gem version is used on a particular project. The Gemfile in a project directory keeps track of the gems used in any project. You can work around the systems permission problem by installing Bundler with a command that uses your home directory for gems. But it is easier to install Ruby with Homebrew or use a version manager and use the Bundler that comes installed, which will correctly set up your local development environment.

Correctly used, Bundler will keep versions of gems for different Ruby versions in separate folders. Bundler will then install multiple versions of gems and use a project Gemfile to load the gems that are needed. Bundler sandboxes each project so that its gem dependencies don't conflict with other projects.

Ruby 2.6 is old!

When you start a project, it is best to use the newest Ruby release.

The system Ruby is Ruby 2.6.10, which is old. As of December 2025, Ruby 4.0 is the current version. If you are just starting with Ruby, install with Homebrew and start your project with the newest Ruby version. When you start building another project, it may be time to install a version manager so you can juggle projects with different Ruby versions.

Leave the system Ruby in place

After you have installed another version of Ruby, leave the system Ruby in place. Don't try to remove it. It is possible that some applications (or Apple's system software) expect to find it.

Update $PATH

How does a terminal application (the shell) know to use a newer version of Ruby that you have installed?

The instructions for installing Homebrew or any version manager will explain how to modify your shell configuration files to update the $PATH variable. See Mac PATH. Issues with running Ruby are usually problems with setting the $PATH.

Future versions of macOS

Apple says:

"Scripting language runtimes such as Python, Ruby, and Perl are included in macOS for compatibility with legacy software. Future versions of macOS won't include scripting language runtimes by default, and might require you to install additional packages."

In future versions, the system Ruby may already be gone (or hidden from you). In that case, you will need to install Ruby with Homebrew or use a version manager.

What to use instead

Instead of the system Ruby, use a version manager to install and manage Ruby:

  • Mise -- a modern, fast version manager for multiple languages including Ruby, Node, Python, and Java. Best choice if you work with more than one language. See Install Ruby with Mise.
  • rv -- a fast, all-in-one Ruby toolchain that installs precompiled Ruby in seconds. Best choice if you only work with Ruby.
  • Homebrew -- convenient for casual users who need only one Ruby version.

For a complete guide, see Install the Latest Ruby Version.

Enjoy Ruby! It is known as a language dedicated to programmer happiness. But remember, the system Ruby is there for macOS, not for you.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.