Learn how to Switch Ruby Versions on Mac (M1, M2, M3, M4 Guide)

Ever tried to set up a new project only to be greeted by the dreaded “wrong Ruby version” error? If you’re nodding along, you’re in good company! As a Mac developer working with Flutter, iOS, or Kotlin Multiplatform projects, managing Ruby versions can feel like trying to herd cats – especially on those shiny new Apple Silicon machines.

I’ve spent countless hours battling Ruby version conflicts on my M1 MacBook Pro, and I’m here to save you from that particular circle of developer purgatory. Let’s walk through the process of switching Ruby versions on your Mac – whether it’s sporting an M1, M2, M3, or M4 chip – with some practical examples and a dash of sanity-preserving advice.

Why Would You Need to Switch Ruby Versions?

Before we dive into the “how,” let’s talk about the “why.” Ruby version management becomes necessary when:

• Your CocoaPods setup for Flutter or iOS development requires a specific Ruby version
• You’re working on multiple projects with different Ruby dependencies
• You need to test your code against different Ruby environments
• Your Kotlin Multiplatform project’s iOS build process has specific Ruby requirements

The system Ruby that comes pre-installed on macOS is like that one friend who never updates their phone – stuck in the past and increasingly incompatible with modern apps. That’s where version managers come in!

The Tools We’ll Use

We’ll be using two main tools:

1. Homebrew – The missing package manager for macOS
2. rbenv – A lightweight Ruby version manager

Let’s get started!

Step 1: Install Homebrew (If You Haven’t Already)

Homebrew makes installing developer tools on macOS as easy as ordering pizza – maybe even easier.

Open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, make sure Homebrew is in your PATH. For Apple Silicon Macs, you might need to add:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify the installation:

brew --version

Step 2: Install rbenv Using Homebrew

Now let’s install rbenv, the tool that will let you switch Ruby versions faster than you can say “dependency conflict”:

brew install rbenv ruby-build

Add rbenv to your shell:

echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

Verify the installation:

rbenv --version

Step 3: Install Different Ruby Versions

Now for the fun part – installing Ruby versions! First, let’s see what versions are available:

rbenv install -l

This will show you a list of available Ruby versions. To install a specific version, run:

rbenv install 3.2.2

This might take a few minutes, so maybe grab a coffee or practice your “waiting for code to compile” face.

Step 4: Switch Between Ruby Versions

Here’s where the magic happens! To switch your global Ruby version:

rbenv global 3.2.2

To set a project-specific Ruby version, navigate to your project directory and run:

rbenv local 3.1.4

This creates a .ruby-version file in your project directory, ensuring anyone who works on the project uses the same Ruby version (assuming they’re also using rbenv).

Verify the active Ruby version:

ruby -v

Troubleshooting Common Issues on Apple Silicon Macs

Apple Silicon Macs (M1/M2/M3/M4) sometimes need extra attention. Here are some common issues and fixes:

Issue 1: “Command not found: rbenv”

If you’ve installed rbenv but your terminal doesn’t recognize it, make sure your PATH is set correctly:

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

Issue 2: Installation Fails with Architecture Errors

If you see errors related to architecture when installing Ruby, try:

arch -arm64 rbenv install 3.2.2

Issue 3: Gems Installation Issues

If you’re having trouble installing gems after switching Ruby versions:

gem update --system

Real-World Example: Setting Up Ruby for a Kotlin Multiplatform Project

Let’s say you’re working on a Kotlin Multiplatform project that requires CocoaPods for the iOS portion. Here’s how to set up the right Ruby environment:

1. Check the required Ruby version in your project (often specified in a .ruby-version file or documentation)
2. Install that version using rbenv:

rbenv install 3.2.2

3. Navigate to your project directory and set the local Ruby version:

cd /path/to/your/kmp/project
rbenv local 3.2.2

4. Install the required gems:

gem install cocoapods

5. Verify everything is working:

pod --version

Now your Kotlin code can happily interact with iOS dependencies without Ruby version conflicts getting in the way!

// In your KMP project's build.gradle.kts
kotlin {
    ios {
        // This will now use the correct Ruby version for CocoaPods integration
        cocoapods {
            summary = "KMP Core Components"
            homepage = "https://github.com/yourusername/yourproject"
            podfile = project.file("../iosApp/Podfile")
        }
    }
}

Using direnv for Project-Specific Environment Variables

For even more control, you can use direnv to automatically switch Ruby versions when entering a project directory. This is especially helpful when working with multiple projects that have different requirements.

Install direnv:

brew install direnv

Add to your shell:

echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

Create a .envrc file in your project directory:

echo 'export RUBY_VERSION=3.2.2' > .envrc
echo 'eval "$(rbenv init -)"' >> .envrc
echo 'rbenv shell $RUBY_VERSION' >> .envrc
direnv allow

Now whenever you enter that directory, direnv will automatically switch to the specified Ruby version!

Comparing Ruby Version Managers

While rbenv is my personal favorite, there are other options available:

Feature	rbenv	RVM	asdf
Simplicity	High	Medium	Medium
Performance	Fast	Slower	Medium
Multi-language support	Ruby only	Ruby only	Multiple languages
Shell integration	Minimal	Deep	Medium
Apple Silicon compatibility	Excellent	Good	Good

If you’re only managing Ruby versions, rbenv is perfect. If you need to manage multiple language versions (Node.js, Python, etc.), asdf might be a better choice.

Keeping Your Ruby Environment Healthy

Once you’ve got your Ruby versions sorted, here are some tips to keep everything running smoothly:

1. Update rbenv regularly:

   brew upgrade rbenv ruby-build

2. Clean up old Ruby versions you no longer need:

   rbenv uninstall 2.7.5

3. Rehash after installing new gems with executables:

   rbenv rehash

4. Check for outdated gems:

   gem outdated

Wrapping Up

Managing Ruby versions on your Mac doesn’t have to be a hair-pulling experience. With rbenv and a few simple commands, you can switch between Ruby versions faster than you can say “dependency conflict resolved!”

Whether you’re working on Flutter projects, iOS apps, or Kotlin Multiplatform applications, having the right Ruby version at your fingertips will save you countless hours of troubleshooting and let you focus on what really matters – building awesome software.

Remember, the next time Ruby gives you version woes, you’re just a few commands away from getting back on track. Happy coding!

---

SEO Optimization

Title: How to Switch Ruby Versions on Mac (M1/M2/M3 Guide)

Meta Description: Learn to easily switch Ruby versions on Mac with rbenv. Perfect for Flutter, iOS & Kotlin Multiplatform developers using Apple Silicon M1, M2, M3 or M4 Macs.

Slug: how-to-switch-ruby-versions-mac-m1-m2-m3-guide

Focus Keyphrase: switch ruby versions mac