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
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 3.1.4. You can either try going straight from 2.6.x to 3.1.4, or in increments: update to 2.6.10, then 2.7.8, then 3.1.4.
The reason to update to at least 3.1.4 as that both Ruby 2.6 and 2.7 have reached end of life, which means they won’t be updated anymore to fix bugs and security issues. The longer you wait to upgrade, the more work you’ll need to do to keep your project secure.
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
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
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
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:
Install Ruby 2.6.10 with Homebrew
Note that the Homebrew team can prevent this at any time because it’s been almost a year since Ruby 2.6.10 was deprecated. For example, see how they disabled Ruby 2.5 last year.
- Install Homebrew if you haven’t already
- Install Ruby 2.6.10:
brew install firstname.lastname@example.org
- 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, and 3.2.2.
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. 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 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.
- Download “Command Line Tools for Xcode 13.4”.
- 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.
- Check that Homebrew is using the correct CLT with
brew config. You should see
CLT: 18.104.22.168.1.1651278267. If not, try reinstalling them.
brew doctorto make sure everything is fine. If not, follow Homebrew’s instructions for fixing issues.
- 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.