Ruby

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

Troubleshoot Ruby Installation

Troubleshoot Ruby installation on Mac. Fix common problems with OpenSSL, version managers, PATH configuration, and gem installs on macOS with Apple Silicon.

Here is help if you have encountered issues installing or running Ruby on a Mac.

Installing Ruby is one step in setting up your Mac for development. See the complete Mac setup checklist.

Before you get started

You'll need a terminal application to install and use Ruby. 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's FREE and worth a try.

Wrong Ruby is active in the shell

This is the most common problem. You install a new Ruby version but the terminal still uses the macOS system Ruby (version 2.6.10). Check which Ruby is active:

$ which ruby

If the result is /usr/bin/ruby, you are using the system Ruby instead of a version manager's Ruby. See Why You Shouldn't Use macOS System Ruby for details.

The fix depends on your version manager. For Mise, make sure your ~/.zshrc contains the Mise activation line. For rv, confirm that rv is initialized in your shell configuration. For chruby, check that both the chruby source line and auto-switching line are in ~/.zshrc. After editing ~/.zshrc, close and reopen the terminal or run source ~/.zshrc.

Version manager not initialized

If your version manager commands are not recognized (for example, command not found: mise or command not found: rv), the version manager is not initialized in your shell configuration file.

Open ~/.zshrc in a text editor and confirm that the initialization line for your version manager is present. Each version manager has a different activation command. See the installation article for your tool: Mise, rv, chruby, or asdf.

After adding or correcting the initialization line, close and reopen the terminal window for the change to take effect.

Asdf "no version set for command"

If you see this error after installing Ruby with asdf:

$ ruby -v
No version set for command ruby
Consider adding one of the following versions in your config file at
ruby 4.0.2

You need to set a default Ruby version. First confirm that a Ruby version is installed:

$ asdf list ruby

If you see a version listed, set it as the global default:

$ asdf global ruby 4.0.2

This creates or updates your ~/.tool-versions file. Close and reopen the terminal, then verify with ruby -v.

OpenSSL not found during Ruby build

When building Ruby from source (through rbenv, asdf, or ruby-build), the build may fail because it cannot find OpenSSL headers or libraries. This is common on Apple Silicon (M-series) Macs where Homebrew installs to /opt/homebrew instead of /usr/local.

First, make sure OpenSSL is installed through Homebrew:

$ brew install openssl

If the build still fails, you may need to tell ruby-build where to find OpenSSL. Set the RUBY_CONFIGURE_OPTS environment variable before running the install:

$ RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl)" rbenv install 4.0.2

For asdf, the same variable works:

$ RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl)" asdf install ruby 4.0.2

You can avoid this problem entirely by using rv or Mise, which install precompiled Ruby binaries and do not require building from source.

Ruby openssl extension fails to compile

If you see The Ruby openssl extension was not compiled after installing Ruby, the Ruby binary was built without OpenSSL support. Gems that require SSL (including Bundler and RubyGems) will not work correctly.

Reinstall Ruby after ensuring OpenSSL is available. Follow the steps in the "OpenSSL not found" section above. If you are building an older Ruby version (3.0 or earlier) on a newer macOS release, the OpenSSL version may be incompatible. Older Ruby versions may require OpenSSL 1.1 instead of the newer OpenSSL 3:

$ brew install [email protected]
$ RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix [email protected])" rbenv install 3.0.7

Legacy Ruby version fails on new macOS

Older Ruby versions (2.7 and earlier) may fail to build on recent macOS releases, especially on Apple Silicon. Common symptoms include compiler errors mentioning maybe_unused, missing symbols, or incompatible architecture warnings.

If you need an older Ruby for a legacy project, try these approaches in order:

  1. Use rv or Mise, which install precompiled binaries and avoid build failures entirely.
  2. If you must build from source, update ruby-build to the latest version (brew upgrade ruby-build) before attempting the install.
  3. Check the ruby-build discussions on GitHub for version-specific workarounds.

The best long-term solution is to upgrade your project to a current Ruby version. Maintaining projects on the latest Ruby reduces technical debt and avoids security risks from unsupported releases.

Homebrew PATH confusion on Apple Silicon

On Apple Silicon (M-series) Macs, Homebrew installs to /opt/homebrew instead of the older Intel location /usr/local. If Homebrew-installed tools are not found, your PATH may not include the correct directory.

Check your PATH:

$ echo $PATH

You should see /opt/homebrew/bin near the beginning. If it is missing, add this line to your ~/.zshrc:

eval "$(/opt/homebrew/bin/brew shellenv)"

Close and reopen the terminal after making changes. See Install Homebrew for full setup instructions.

SSL certificate verification errors

If you get Gem::RemoteFetcher::FetchError: SSL_connect or OpenSSL certificate verify failed when installing gems, Ruby cannot verify SSL certificates from RubyGems.org.

On modern macOS with a current Ruby version, this is rare. If it happens, first update RubyGems and the SSL certificates:

$ gem update --system

If the problem persists, reinstall Ruby through your version manager. A fresh install will pick up the current certificate bundle from Homebrew's OpenSSL.

Bundler version mismatch

If you see the running version of Bundler is older than the version that created the lockfile when running Rails commands, the Bundler version in your Ruby installation does not match the version recorded in your project's Gemfile.lock.

The simplest fix is to update Bundler:

$ gem install bundler

Then run bundle install in your project directory. If the project requires a specific older Bundler version, install that version explicitly:

$ gem install bundler -v '2.4.22'

You can also prefix commands with bundle exec (for example, bundle exec rails server) to ensure the correct Bundler version runs. For detailed Bundler troubleshooting including the DidYouMean error and old project lockfile problems, see Check Ruby Gems and Bundler.

Gem pristine warning

If you get a warning Ignoring ... because its extensions are not built. Try: gem pristine ..., close and reopen the terminal window to start a new session and try again. If the warning persists, run the suggested gem pristine command to rebuild the gem's native extensions.

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.