Fixing "Your Ruby version is 2.6.8, but your Gemfile specified 2.7.5" in React Native

Problem Statement

When trying to create a React Native project using npx react-native init AwesomeProject, you encounter the error:

Your Ruby version is 2.6.8, but your Gemfile specified 2.7.5

This issue occurs because:

1. macOS ships with its own system Ruby (version 2.6.8 in macOS Monterey)
2. React Native requires Ruby 2.7.5 for iOS dependencies
3. The version mismatch breaks CocoaPods installation during project initialization

The root cause is incompatibility between your system's Ruby version and the version required by React Native's iOS tools.

Why you shouldn't modify macOS system Ruby

Apple's system tools rely on the built-in Ruby installation. Modifying it directly can cause system instability and permission issues. Use a version manager instead.

Recommended Solution: Use rbenv (Ruby Version Manager)

This is the cleanest approach to manage multiple Ruby versions. Follow these steps:

Step 1: Install rbenv and ruby-build

brew update
brew install rbenv ruby-build

Step 2: Initialize rbenv in your shell

Add to .zshrc for macOS Monterey and later:

Zsh

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

Bash

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

Step 3: Install Required Ruby Version

rbenv install 2.7.5

Step 4: Set as Global Default

rbenv global 2.7.5

Step 5: Verify Installation

ruby -v
# Should show: ruby 2.7.5...

Step 6: Install Bundler

gem install bundler

Step 7: Retry Project Initialization

npx react-native init AwesomeProject

Fixing React Native CLI Failure

If project creation fails partially:

cd AwesomeProject/ios
bundle install && bundle exec pod install
cd ../
npx react-native run-ios

Alternative Version Managers

If you prefer different tools:

Using RVM

\curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm
rvm install 2.7.5
rvm use 2.7.5 --default

Using asdf

asdf plugin add ruby
asdf install ruby 2.7.5
asdf global ruby 2.7.5

Common Issues and Solutions

Gem Path Conflicts

After installation errors:

gem env home # Copy the path
echo 'export GEM_HOME="<path_from_gem_env_home>"' >> ~/.zshrc
source ~/.zshrc

Bundle Command Conflicts

rm /usr/local/bin/bundle

Cache Issues

Clear cache and reboot:

rm -rf ~/Library/Caches/

Workarounds (Not Recommended)

Modify Gemfile version as temporary fix (only if version managers fail):

# Change this line in ios/Gemfile
ruby '2.6.8' # Instead of 2.7.5

cd ios
bundle install

Version Limitation

This may cause compatibility issues with CocoaPods dependencies. Use only for testing.

Complete Environment Setup

For a fully configured environment:

1. Install Homebrew:
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. Install watchman:
   brew install watchman
3. Install latest Xcode (App Store)
4. Install rbenv and Ruby 2.7.5 (use instructions above)
5. Install CocoaPods:

   sudo gem install cocoapods
   sudo gem install -n /usr/local/bin ffi cocoapods

System Check

Ensure compatibility with your environment:

Component	Tested Version
macOS	Monterey (12.6)
Xcode	14.0.1
Chip Architecture	Apple M2/Intel

Prevent Future Issues

1. Always verify Ruby version before creating projects:

   ruby -v

2. Update .ruby-version file in your projects
3. Periodically clean cache with bundle clean --force

Using a Ruby version manager provides a sustainable solution, allowing painless version switching for different projects while keeping macOS system Ruby untouched.

Final Solution Choice

While workarounds exist, rbenv is the strongest solution that properly resolves the version conflict. All StackOverflow answers ultimately converge on version managers as the correct approach.