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

Struggling with Ruby version conflicts on your Apple Silicon Mac (M1/M2/M3/M4)? Whether you’re setting up CocoaPods for Flutter, Kotlin Multiplatform (KMP/KMM), or iOS development, this step-by-step guide will help you manage Ruby versions effortlessly using rbenv and Homebrew. Say goodbye to compatibility headaches—let’s get started!

Why Ruby Version Management Matters for Mac Developers

Ruby version conflicts can derail workflows, especially when tools like CocoaPods or Xcode require specific versions. With Apple Silicon Macs (M1, M2, M3, M4), outdated guides often lead to wasted hours. Follow this tutorial to:

✅ Install and configure Homebrew (macOS package manager)
✅ Use rbenv to switch Ruby versions seamlessly
✅ Fix “Command Not Found” errors on Apple Silicon
✅ Ensure compatibility with Flutter, KMP, and iOS projects

Step 1: Install Homebrew on Mac

Homebrew simplifies installing developer tools on macOS. For Apple Silicon Macs (M1/M2/M3/M4):

1. Open Terminal.
2. Run:

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

3. Verify with:

   brew --version  
   

Step 2: Set Up rbenv for Ruby Version Management

rbenv lets you install and switch Ruby versions in seconds:

1. Install rbenv and ruby-build:

   brew install rbenv ruby-build  
   

2. Initialize rbenv in your shell profile:

   rbenv init  
   

3. Add these lines to ~/.zshrc (or ~/.bash_profile):

   export PATH="$HOME/.rbenv/bin:$PATH"  
   eval "$(rbenv init -)"  
   

4. Reload the profile:

   source ~/.zshrc  
   

Step 3: Install & Switch Ruby Versions

Check Current Ruby Version

ruby -v  

Install a New Ruby Version (e.g., 3.3.6)

1. List available versions:

   rbenv install -l  
   

2. Install your target version:

   rbenv install 3.3.6  
   

3. Set it as default:

   rbenv global 3.3.6  
   

Verify the Change

ruby -v  
# Output: ruby 3.3.6 (arm64-darwin24)  

Troubleshooting: Fix Old Ruby Version on Apple Silicon

If Terminal still shows the system Ruby:

1. Update ~/.zprofile:

   nano ~/.zprofile  
   

2. Add:

   export PATH="$HOME/.rbenv/bin:$PATH"  
   eval "$(rbenv init - zsh)"  
   

3. Save and reload:

   source ~/.zprofile  
   

Bonus: Use asdf for Multi-Language Version Management

For developers juggling Ruby, Node.js, and Java, asdf is a versatile alternative. Install via Homebrew:

brew install asdf  

Conclusion: Streamline Your Mac Development Setup

You’ve now mastered Ruby version management on M1/M2/M3/M4 Macs! No more wasted hours on CocoaPods errors or Xcode incompatibilities. For more guides on Flutter, KMP, or iOS tools, explore our blog.

External Links:

• Homebrew Official Docs
• rbenv GitHub