Ruby Version Mismatch: Installed 2.6.8 vs. Gemfile Specified 2.7.5 – How to Fix on macOS Monterey for React Native Setup

Setting up a React Native project on macOS Monterey can be exciting—until you hit a roadblock like a Ruby version mismatch. If you’ve encountered an error like “Your Ruby version is 2.6.8, but your Gemfile specified 2.7.5” when running bundle install or pod install, you’re not alone.

macOS Monterey (and many earlier versions) ships with a pre-installed system Ruby (often 2.6.8), but React Native projects frequently require newer versions (like 2.7.5) specified in their Gemfile to ensure compatibility with dependencies like CocoaPods (used for iOS setup). Modifying the system Ruby directly is risky (it can break macOS tools), so we’ll use a Ruby version manager to safely resolve this mismatch.

This guide walks you through fixing the version conflict step-by-step, ensuring a smooth React Native setup on macOS Monterey.

Table of Contents#

  1. Understanding the Ruby Version Mismatch
  2. Prerequisites
  3. Step 1: Install a Ruby Version Manager (rbenv)
  4. Step 2: Install the Required Ruby Version (2.7.5)
  5. Step 3: Set Ruby 2.7.5 for Your React Native Project
  6. Step 4: Update Gems and Bundler
  7. Step 5: Reinstall Dependencies (Bundle & Pods)
  8. Verifying the Fix
  9. Troubleshooting Common Issues
  10. Conclusion
  11. References

Understanding the Ruby Version Mismatch#

Why Does This Happen?#

macOS Monterey includes a system Ruby (typically 2.6.8) for internal use. This Ruby is not intended for development, and modifying it can cause critical macOS tools to fail.

React Native projects, however, use Ruby to manage iOS dependencies via CocoaPods. The project’s Gemfile specifies a Ruby version (e.g., 2.7.5) to ensure all contributors and tools use the same environment. When your terminal uses the system Ruby (2.6.8) instead of the project’s required version (2.7.5), you get the mismatch error.

Example Error Message#

You’ll likely see this when running bundle install or pod install in your React Native project:

Your Ruby version is 2.6.8, but your Gemfile specified 2.7.5

Prerequisites#

Before fixing the mismatch, ensure you have these tools installed:

  • Xcode Command Line Tools: Required for compiling Ruby and iOS dependencies. Install via: 
    xcode-select --install
  • Homebrew: The macOS package manager, used to install Ruby version managers. Install from brew.sh if missing: 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 1: Install a Ruby Version Manager (rbenv)#

A version manager lets you install/switch between Ruby versions without touching the system Ruby. We’ll use rbenv (lightweight and widely recommended).

Install rbenv and ruby-build#

rbenv itself manages Ruby versions, while ruby-build is a plugin that simplifies installing new Ruby versions.

brew install rbenv ruby-build

Configure Your Shell#

Add rbenv to your shell profile (zsh is default on macOS Monterey) to make the rbenv command available.

  1. Open your shell config file (e.g., ~/.zshrc for zsh or ~/.bash_profile for bash):

    nano ~/.zshrc

  2. Add these lines to the end of the file:

    # Load rbenv
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init - zsh)"  # Use "bash" instead of "zsh" if using bash

  3. Save and exit (Ctrl+O, Enter, Ctrl+X in nano).

  4. Restart your terminal or reload the config:

    source ~/.zshrc  # or source ~/.bash_profile

Verify rbenv Installation#

Check if rbenv works:

rbenv --version

You should see output like rbenv 1.2.0 (version may vary).

Step 2: Install the Required Ruby Version (2.7.5)#

Now install Ruby 2.7.5 (the version specified in your Gemfile).

Install Dependencies for Ruby#

Ruby requires libraries like openssl and readline to compile. Install them via Homebrew:

brew install [email protected] readline

Install Ruby 2.7.5 with rbenv#

Use rbenv install to fetch and compile Ruby 2.7.5. This may take 5–10 minutes (Ruby compiles from source).

# Install Ruby 2.7.5 (specify openssl path to avoid errors)
RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix [email protected]) --with-readline-dir=$(brew --prefix readline)" rbenv install 2.7.5

Verify Ruby Installation#

Check if 2.7.5 is installed:

rbenv versions

You’ll see 2.7.5 in the list (marked with * if active).

Step 3: Set Ruby 2.7.5 for Your React Native Project#

Tell rbenv to use 2.7.5 in your project directory.

Set Local Version (Project-Specific)#

Navigate to your React Native project folder and set 2.7.5 as the local version:

cd /path/to/your/react-native-project
rbenv local 2.7.5

This creates a .ruby-version file in your project, ensuring anyone else using rbenv will also use 2.7.5.

(Optional) Set Global Version (System-Wide)#

To use 2.7.5 as the default Ruby version across all projects (optional):

rbenv global 2.7.5

Verify the Active Ruby Version#

Check if 2.7.5 is now active:

ruby -v

Output should be: ruby 2.7.5p203 (2021-11-24 revision f69aeb8314) [x86_64-darwin21] (or similar for Apple Silicon).

Step 4: Update Gems and Bundler#

RubyGems (Ruby’s package manager) and Bundler (manages project dependencies) may need updates for 2.7.5.

Update RubyGems#

gem update --system

Install Bundler#

Bundler reads the Gemfile and installs specified dependencies. Install it:

gem install bundler

Step 5: Reinstall Dependencies (Bundle & Pods)#

Now re-install your project’s Ruby dependencies and iOS pods.

Install Project Gems with Bundler#

In your React Native project folder:

bundle install

This installs gems specified in Gemfile (e.g., cocoapods for iOS).

Install iOS Pods#

Finally, install CocoaPods dependencies for iOS:

cd ios  # Navigate to the iOS directory
pod install

Verifying the Fix#

Your Ruby version mismatch should now be resolved! Confirm with these checks:

  1. Ruby Version: In your project folder, run ruby -v – should show 2.7.5.
  2. Bundle Install: Run bundle install – no version mismatch errors.
  3. Pod Install: Run pod install in the ios folder – completes without Ruby-related errors.

Troubleshooting Common Issues#

Issue: rbenv: command not found#

Fix: Ensure rbenv is in your shell PATH. Recheck Step 1.2 (shell config). Restart your terminal or run source ~/.zshrc.

Issue: Ruby 2.7.5 Fails to Install (Compilation Errors)#

Fix: Missing dependencies. Reinstall [email protected] and readline, then retry the install with the RUBY_CONFIGURE_OPTS command from Step 2.2.

Issue: pod: command not found#

Fix: After switching Ruby versions, reinstall CocoaPods:

gem install cocoapods

Issue: Permission Errors with gem install#

Fix: Never use sudo with gem when using rbenv (it bypasses the version manager). If you see permission denied, ensure rbenv’s Ruby is active (ruby -v shows 2.7.5).

Conclusion#

By using rbenv to manage Ruby versions, you’ve safely resolved the version mismatch and ensured your React Native project uses the required Ruby 2.7.5. This approach avoids modifying macOS’s system Ruby and keeps your development environment isolated and reproducible.

With the mismatch fixed, you can now proceed to build and run your React Native app on iOS!

References#

2026-08