Easily Switch Ruby Versions on Your Mac (M1, M2, M3, M4 Included)
Are you tired of wrestling with Ruby version updates and installations on your Mac? Whether you’re configuring tools like CocoaPods for Flutter, Kotlin Multiplatform(KMP/KMM), iOS development or need different Ruby versions for your projects, this guide saves your day (and time!).
With these simple steps, you can seamlessly switch Ruby versions in just 5 minutes. I spent hours to figuring this out, so consider this your ultimate time-saving gift.
Why You Need This Guide
Managing Ruby versions manually can be a headache, especially if you’re juggling different projects that require specific Ruby versions. This step-by-step tutorial will show you how to:
- Install and configure Homebrew.
- Use
rbenv
to manage multiple Ruby versions effortlessly. - Update your system to recognize the new versions instantly.
Let’s dive in!
Step 1: Install Homebrew
Homebrew is a versatile package manager that simplifies software installation on macOS. If you haven’t installed Homebrew yet, here’s how to do it:
- Open your terminal.
- Copy and paste this command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Follow the on-screen instructions to complete the installation process.
To verify that Homebrew is installed, run:
brew --version
Step 2: Install rbenv and ruby-build
rbenv
is the go-to tool for managing multiple Ruby versions. With Homebrew installed, you can set up rbenv
in a snap:
brew install rbenv ruby-build
Step 3: Initialize rbenv
Once installed, you need to initialize rbenv
so your system knows how to use it:
rbenv init
Follow any additional instructions provided in the terminal output. Typically, you’ll need to update your shell configuration file (.zshrc or .bash_profile) to include:
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"
Save the file and reload your terminal or source the file:
source ~/.zshrc
Step 4: Check Your Current Ruby Version
Before installing a new version, let’s see which Ruby version your Mac is currently using:
ruby -v
Step 5: Install a New Ruby Version (Optional)
Want to upgrade or switch to another version? Here’s how:
- List all available Ruby versions:
rbenv install -l
3.1.6
3.2.6
3.3.6
jruby-9.4.9.0
mruby-3.3.0
picoruby-3.0.0
truffleruby-24.1.1
truffleruby+graalvm-24.1.1
- Install your desired version. For example, to install Ruby 3.3.3:
rbenv install 3.3.6
- Set it as the global default:
rbenv global 3.3.6
Step 6: Verify the Installed Ruby Version
After installation, confirm your Ruby version with:
ruby -v
-> ~ ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [arm64-darwin24]
This should now display the newly installed version.
Step 7: Update Your Shell Profile (If Necessary)
Sometimes, your terminal might still show the old Ruby version. To fix this, update your shell profile (e.g., .zprofile
):
- Open the file in a text editor:
nano ~/.zprofile
- Add these lines:
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init - zsh)"
- Save and close the file (Ctrl + O, then Ctrl + X in nano).
- Reload your shell profile:
source ~/.zprofile
- Verify again with:
ruby -v
Step 8: Enjoy Hassle-Free Ruby Management
That’s it! You’ve successfully switched your Ruby version. Now your Mac is optimized for smooth Flutter, KMP, iOS development and beyond.
Bonus Tip: Consider asdf for Ruby Management
While rbenv
is a fantastic tool, you might also explore asdf, a version manager that supports multiple runtimes, including Ruby. It’s versatile and might suit developers working with various languages.
Conclusion
By following this guide, you’ve streamlined your Ruby setup, ensuring a smoother workflow for iOS development and other Ruby-based projects. No more version conflicts or tedious installations—just pure productivity.
Keywords: Ruby, Mac, M1, M2, M3, M4, rbenv, CocoaPods, KMP, Flutter, iOS development, Ruby version management, Homebrew, macOS tools
Inspired By: Luiz Gadão