Running pod on a React Native project fails with can't find gem cocoapods
can't find gem cocoapods (>= 0.a) with executable podShort answer
The pod command exists, but the Ruby that is running it has no CocoaPods gem. This happens after a Ruby switch, with a different GEM_HOME, or when CocoaPods was never installed for this project. Check gem list cocoapods, then run bundle install and bundle exec pod install inside the project.
Fix it fast
1Find out which cause you have
Ask RubyGems whether the Ruby in this terminal has CocoaPods, and which folders it searches.
which ruby pod gem list cocoapods gem environment home gem environment path2Match what you see, then jump to its fix
- 1
The project folder has a Gemfile and you ran plain pod installThe project uses Bundler but bundle install was never runFix - 2
gem list cocoapods prints nothing, but pod worked earlierThe active Ruby changed and the gem lives in another RubyFix - 3
gem install --user-install was used, or GEM_HOME is set in one terminal and not anotherThe gem was installed into the user directory and GEM_HOME or PATH does not matchFix
- 1
What does the error look like?
can't find gem cocoapods (>= 0.a) with executable pod
Cause 1 of 3
The project uses Bundler but bundle install was never run
1Check
The React Native template README says to run bundle install the first time to install CocoaPods itself, and bundle exec pod install after that. Look for the Gemfile in the project root.
ls Gemfile
gem list cocoapods2Fix
Install the gems from the Gemfile, then run pod through Bundler from the ios folder's parent.
bundle install
cd ios
bundle exec pod install3Verify
bundle exec pod install finishes and creates the Pods folder.
bundle exec pod --versionConfirmed by github.com
Cause 2 of 3
The active Ruby changed and the gem lives in another Ruby
1Check
RubyGems installs into GEM_HOME and searches GEM_PATH. Switching Ruby with rbenv, RVM or Homebrew gives you a different set of gems, so a pod command left on your PATH can no longer find its gem.
ruby -v
gem environment home
gem environment path2Fix
Install CocoaPods into the Ruby you are using now. CocoaPods advises against the Ruby that ships with macOS and suggests a managed Ruby from RVM, rbenv or Homebrew. For a project that has a Gemfile, prefer bundle install from the first cause.
gem install cocoapods3Verify
The gem is listed under the active Ruby.
gem list cocoapods
pod --versionConfirmed by guides.cocoapods.org
Cause 3 of 3
The gem was installed into the user directory and GEM_HOME or PATH does not match
1Check
RubyGems documents that --user-install puts gems in your home directory instead of GEM_HOME, and that GEM_PATH is the list of folders searched. If the shell that runs pod does not see that folder, the executable cannot find its gem.
gem environment path
gem which cocoapods2Fix
Use one place for gems. CocoaPods suggests setting GEM_HOME and adding its bin folder to PATH in your shell profile, then installing again.
# ~/.zshrc
export GEM_HOME=$HOME/.gem
export PATH=$GEM_HOME/bin:$PATH
# then, in a new terminal:
gem install cocoapods3Verify
A new terminal finds the gem and the executable.
gem list cocoapods
pod --versionConfirmed by guides.rubygems.org
How do I stop it coming back?
- Keep a Gemfile in the project and always run bundle exec pod install, so the CocoaPods version is the same for every machine.
- Pick one Ruby manager and do not mix it with the macOS system Ruby.
- After switching Ruby versions, run bundle install again in each project.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
pod install cannot pick a version of a pod that satisfies every requirement
Specs satisfying the `FirebaseAuth (~> 11.0)` dependency were found, but they required a higher minimum deployment target.
CocoaPods tried every version of the named pod and none fit all requirements.
4 causes, each with a fixMobile apps
Axios request works on iOS or in a browser but fails on Android with Network Error
AxiosError: Network Error
A React Native app has no CORS, so on Android a Network Error usually means the request never reached the server.
3 causes, each with a fixMobile apps
Axios returns Network Error in a React Native app on iPhone or the iOS Simulator
error.code is ERR_NETWORK and error.response is undefined
A Network Error means iOS stopped the request before any HTTP answer came back.
3 causes, each with a fixMobile apps
backgroundImage: url(...) does nothing in a React Native view
ImageBackground renders an empty area
In React Native the backgroundImage style draws linear and radial gradients, not pictures, so url(...) is ignored.
3 causes, each with a fixMobile apps
A custom font in React Native falls back to the system font
Unrecognized font family 'MyFont'
React Native does not report a missing font, it just draws the system font.
6 causes, each with a fixMobile apps
fetch fails with TypeError: Network request failed in React Native
Network request failed
Network request failed means the request never got an HTTP response, so there is no status code to read.
3 causes, each with a fix