How to Install Ruby 2.6.x on macOS (Sonoma, Ventura and Monterey)

Published by Moncef Belyamani on
Updated on

“How can I install Ruby 2.6.x on an Apple Silicon Mac (M1/M2/M3)?” I get asked this question a lot, and I see it often in the various online Ruby hangouts. People try all kinds of things but no one seems to be able to succeed. Some people say to use Rosetta, and others say forget about 2.6 and update your project to 2.7.

The truth is that it is possible to install Ruby 2.6 on an Apple Silicon Mac, and in this article I’ll show you 3 different ways to do that. You can skip directly to each solution with the links below, but I highly recommend reading the whole article to better understand how Ruby installation works on a Mac, and why most solutions people try don’t work.

Hey Moncef, do your solutions only work with 2.6.10? I need an older version!

This is another common source of confusion because people don’t understand how Ruby versioning works. They get stuck because they think they have to use the version of Ruby that’s specified in the project’s .ruby-version and/or Gemfile. Instead, it’s recommended to update the project to at least the latest patch version (the third digit).

For example, if your project is currently using Ruby 2.6.6, or any version of 2.6 lower than 2.6.10, the first thing I recommend you do is update it to at least 2.6.10. As I explain in my guide about how and why to upgrade the Ruby version in your project, it rarely makes sense to use a Ruby version where the 3rd digit is not the latest one.

Another reason for upgrading to 2.6.10 is that it is MUCH easier to safely install 2.6.10 on an Apple Silicon Mac than versions older than 2.6.8, which require Rosetta. Some people might tell you to use some variation of optflags=-Wno-error=implicit-function-declaration to avoid using Rosetta, but I guarantee that if you ask them what it does, they won’t be able to tell you.

It’s possible that it might allow older Ruby versions to be installed without using Rosetta, but just because Ruby installed fine doesn’t mean it’s safe, and it doesn’t mean it won’t cause issues down the line that you’ll have a hard time troubleshooting. For example, you might not be able to run your Rails app due to the infamous dyld: missing symbol called error.

What that setting does is it disables errors when functions can’t be found. By default, errors are turned on by default on macOS, for a very good reason. You want to make sure everything Ruby needs is there and that it will behave properly. I personally wouldn’t want to disable something macOS does by default.

Benoit Daloze, one of the maintainers of rbenv and ruby-build, some of the most popular Ruby version managers, explains in more detail why it is dangerous to disable this setting:

Actually it can be a pretty dangerous workaround, because then the compiler does not know precise argument types and could end up passing arguments incorrectly, which could cause all kinds of problems (e.g., if the prototype is var-args it’d probably crash or corrupt the arguments on aarch64).

It is also always a clear bug in the source for not properly including functions it uses, and missing an include e.g. can result in incorrect compilation, not defining the macros as needed, not using an intrinsified version of the function, etc.

Also BTW recent CRuby enables that flag by default, and it would be very bad to disable something CRuby enables on purpose

How Ruby installation works on a Mac

Some people will tell you that Ruby 2.6 is not compatible with Apple Silicon Macs. Yet, later versions of Monterey (macOS 12), Ventura (macOS 13) and Sonoma (macOS 14) all come preinstalled with Ruby 2.6.10. That proves that it is possible to install it on both Intel and Apple Silicon Macs.

However, this version of Ruby preinstalled by Apple is not meant to be used for development. Read my article that goes over 5 reasons why you shouldn’t use the system Ruby on macOS.

Instead, you’ll want to use a special tool that can install a separate version of Ruby that doesn’t interfere with the one that Apple installed. These tools, known as version managers, can install multiple versions of Ruby at the same time, and let you easily switch between them. The most popular ones are asdf, chruby/ruby-install, frum, rbenv/ruby-build, and rvm.

The problem is that most of these version managers (when used out of the box with their default settings) fail to install Ruby 2.6.x on any Mac running on macOS Ventura (13.x) or Sonoma (14.x), and in some cases on the latest version of Monterey (12.6.x) that has version 14 or higher of Apple’s command line tools (CLT).

Assuming you have Homebrew installed, you can check which version of the CLT you have by running brew config, and then look towards the bottom for the lines that start with CLT: and/or Xcode:

The reason why some version managers can’t install certain versions of Ruby is because they all compile Ruby from scratch, and whether or not the installation succeeds depends on many factors, but these are the main ones on a fresh macOS installation:

  • The CLT version
  • The macOS version
  • The Mac chip (Intel or Apple Silicon)
  • How the version manager configured Ruby
  • Whether or not you have prerequisite tools installed (many version managers don’t install them for you)

Each version manager configures Ruby differently, which is why you might be able to install a particular version with ruby-install for example, but not with rvm. Note that these version managers allow you to override some or all Ruby configuration settings, but the vast majority of people use the default settings. This makes sense because modifying anything would require deep knowledge of how Ruby configuration and compilation works.

For example, rvm often fails to install various Ruby versions with this error (the number after -j might change; it refers to the number of cores your Mac has):

Error running '__rvm_make -j12'

If you look up that error on their GitHub page, you’ll see many people offering various solutions, but they don’t work for everyone. And even if they did work, they’re usually not the right way to fix the problem.

In addition, the way Ruby needs to be configured depends on the Ruby version. However, most version managers use the same settings for all versions. One exception is ruby-build (the tool that both rbenv and asdf use to install Ruby) which uses an appropriate version of OpenSSL depending on the Ruby version. That’s not enough in some cases, though, and the fact that ruby-build compiles its own version of OpenSSL has some downsides, such as taking longer to install Ruby.

That’s why I built Ruby on Mac. It’s the result of twelve years of helping thousands of people set up a reliable Ruby dev environment on their Mac. I also continuously spend hundreds of hours researching and testing various Ruby versions on 4 different Macs using all kinds of scenarios. Ruby on Mac guarantees a successful installation of any supported Ruby version on macOS 14 (Sonoma), 13 (Ventura), and 12 (Monterey). That includes Ruby versions as old 1.9.3 and above with the Ultimate version of Ruby on Mac, and Ruby versions 3.1.x and above with Prime.

What about Rosetta?

Some people will tell you they found a solution using Rosetta, but that means one of these two results:

  • They end up doing all of their dev work with Rosetta, which is a shame not to take full advantage of the Apple Silicon chip.

  • They try to set up two dev environments — one with Rosetta, and one in native mode — and they inevitably run into all kinds of issues. Then they waste time either trying to fix them or removing everything and starting over from scratch.

The good news is that if you’ve been using Rosetta to work on a Ruby 2.6.x project, you can use Ruby on Mac’s “reset” mode, which will safely back up, then clean up your dev setup in 1 minute, and then you can run it in “normal” mode to reinstall everything from scratch in native mode. And then you can install Ruby 2.6.10 with a single command:

rom install ruby 2.6.10

It’s worth pointing out that if you do need to work on really old apps that use Ruby versions older than 2.6, Ruby on Mac Ultimate makes it easy to set up a proper dev environment with Rosetta that won’t interfere with the native Apple Silicon setup.

Now that you have a basic understanding of what can cause Ruby installation to fail, let’s go over three solutions for installing Ruby 2.6.10 on your Mac, from easiest to most time-consuming:

  • Install Ruby 2.6.10 with Ruby on Mac Ultimate
  • Install Ruby 2.6.10 with Homebrew (this is no longer possible as of June 19, 2023)
  • Downgrade to version 13.4 of the command line tools (doesn’t work on Ventura or Sonoma)

Install Ruby 2.6.10 with Ruby on Mac Ultimate

With Ruby on Mac Ultimate, installing Ruby 2.6.10 on Sonoma, Ventura or Monterey is as easy as running this command (after installing Ruby on Mac):

rom install ruby 2.6.10

You don’t have to do anything else to configure it, and you don’t have to mess with your PATH or shell file to be able to switch to other Ruby versions.

To start using 2.6.10, you’ll quit and restart your terminal, then run this command:

chruby 2.6.10

Ruby on Mac Ultimate also lets you install Ruby versions as old as 1.9.3 on Ventura and Monterey, and as old as 2.3.x on Sonoma!

Install Ruby 2.6.10 with Homebrew

Note that the Homebrew team can prevent this at any time because it’s been about 2 years since Ruby 2.6.10 was deprecated. For example, see how they disabled Ruby 2.5 in 2022.

UPDATE: Ruby 2.6 has now been officially disabled on Homebrew on June 19, 2023, so the rest of this section won’t work anymore.

  1. Install Homebrew if you haven’t already
  2. Install Ruby 2.6.10: brew install ruby@2.6
  3. Follow the instructions for setting your PATH. For example, Homebrew will say something like this:
By default, binaries installed by gem will be placed into:
  /opt/homebrew/lib/ruby/gems/2.6.0/bin

You may want to add this to your PATH.

If you need to have ruby first in your PATH, run:
  echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc

The reason Homebrew is able to install 2.6.10 is because this is a pre-built version of Ruby that was compiled with version 13.3 of the command line tools. However, note that it’s not officially supported.

Unless you know what you’re doing, in order to use the Homebrew Ruby, you’ll need to disable any other version manager you might have used before (such as asdf, chruby, frum, rbenv, or rvm). And you’ll only be able to use 2.6.10 with this setup. You won’t be able to switch to other versions that you might have installed with another version manager, unless you make changes to your shell file to disable the Homebrew Ruby and turn your version manager setup back on. You’ll have to keep doing this each time you want to switch between 2.6.10 and other versions.

This is meant as a temporary solution so that you can run your project with 2.6.10 and then update it to 2.7.8, and then 3.1.4, and so on. Also, note that either way, you’ll need to update your project to at least 2.6.10. There’s absolutely no reason to use any other version of Ruby 2.6.x. For security reasons, it’s recommended to make sure your apps are running the latest version in a series. For 2.6, it’s 2.6.10, for 2.7, it’s 2.7.8, then 3.0.6, 3.1.4, 3.2.3, and 3.3.0.

Downgrade to version 13.4 of the command line tools

This is not possible on macOS Ventura (13.x) or Sonoma (14.x), so don’t waste your time trying. Depending on how old and complex your project is, it might take you less time to update your project to 2.7.8 than it would to downgrade from Ventura or Sonoma to Monterey.

If you’re on macOS Monterey, follow the steps below to download and install version 13.4 of the command line tools. Note that this is not guaranteed to work, depending on which version of Monterey you’re running. I had success with macOS 12.1, but some issues with 12.6.

Note that it should never be necessary to download the huge 7GB Xcode app unless you’re building macOS and iOS apps. In other words, if you’re never going to use the Xcode app itself, all you need are the standalone Command Line Tools.

  1. Download “Command Line Tools for Xcode 13.4”.
  2. Install them, but keep the DMG when it asks you if you want to Trash it, just in case you need to install them again.
  3. Check that Homebrew is using the correct CLT with brew config. You should see CLT: 13.4.0.0.1.1651278267. If not, try reinstalling them.
  4. Run brew doctor to make sure everything is fine. If not, follow Homebrew’s instructions for fixing issues.
  5. Install Ruby 2.6.10 with your favorite Ruby version manager. If you haven’t yet installed a version manager, you can either buy Ruby on Mac, which will set everything up for you in 15 minutes, or spend an hour following my step-by-step guide for installing Ruby on a Mac.