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

"How can I install Ruby 2.6.x on a Mac M1/M2?" 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.

• Install Ruby 2.6.10 with Ruby on Mac Ultimate
• Install Ruby 2.6.10 with Homebrew
• Downgrade to version 13.4 of the command line tools (does not work with Ventura)

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 2.6.10. And then the next thing you want to prioritize is updating it to 2.7.7 because Ruby 2.6 reached end of life in March 2022, which means it has known bugs and security issues that will never be fixed. Note that you can also go straight from 2.6.x to 2.7.7.

This is super important to understand, so please read my guide that explains how and why to upgrade the Ruby version in your project.

How Ruby installation works on a Mac

Some people will tell you that Ruby 2.6 is not compatible with Apple Silicon Macs. Yet, Ventura comes preinstalled with Ruby 2.6.10 on all Macs. That proves that it is possible to install it on Ventura 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 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), 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 five main factors:

• 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 asdf or rbenv. 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.

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.

That's why I built Ruby on Mac. It's the result of eleven 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 13 (Ventura), 12 (Monterey), and 11 (Big Sur). For now, that includes 2.6.10 and above with Ultimate, and 2.7.x and above with Prime. I'm working on adding support for super old Ruby versions like 2.3.x, but I need to do more testing.

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.

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
• Downgrade to version 13.4 of the command line tools (doesn't work on Ventura)

Install Ruby 2.6.10 with Ruby on Mac Ultimate

With Ruby on Mac Ultimate, installing Ruby 2.6.10 on 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

Install Ruby 2.6.10 with Homebrew

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.7, and then 3.1.3, 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.7, then 3.0.5, 3.1.3, and 3.2.1.

Downgrade to version 13.4 of the command line tools

This is not possible on macOS Ventura (13.x), so don't waste your time trying. It will probably take you less time to update your project to 2.7.7 than it would to downgrade from Ventura 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. Reinstall all Ruby-related tools with Homebrew:

brew reinstall automake bison gdbm libffi libyaml openssl@1.1 openssl@3 readline

1. 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.