Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

The shell cannot find pod although the CocoaPods gem installed

Errorzsh: command not found: pod

Short answer

The gem is installed, but the folder holding its pod executable is not on your PATH, or you are on a different Ruby than the one that installed it. Ask RubyGems where it puts executables with gem environment, add that folder to PATH, and make sure the same Ruby runs gem and pod.

  • Applies to CocoaPods, RubyGems, rbenv, zsh on macOS
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask RubyGems which Ruby it is and where it puts executables, then check whether pod is already in one of those folders.

    which -a ruby gem
    gem environment
    gem list cocoapods
  2. 2Match what you see, then jump to its fix

    1. 1gem list cocoapods shows the gem, but pod is not found by nameThe gem was installed with --user-install and its bin folder is not on PATHFix
    2. 2which -a ruby shows more than one Ruby, or gem list cocoapods is empty in this folder but not elsewhereA Ruby version manager is using a different Ruby than the one that installed the gemFix
    3. 3gem install ended without errors, but no pod file exists in the usual bin foldersThe install used sudo or a custom install directory, so the executable went elsewhereFix

What does the error look like?

  • zsh: command not found: pod
  • command not found: pod

Cause 1 of 3

The gem was installed with --user-install and its bin folder is not on PATH

1Check

A user install puts the gem under your home folder. The CocoaPods guide says you still have to set PATH in your shell profile, or run the command by its full path.

gem environment | grep -A4 "EXECUTABLE DIRECTORY\|GEM PATHS"
ls ~/.gem/ruby/*/bin 2>/dev/null

2Fix

Add the executable directory that gem environment printed to PATH in ~/.zshrc, open a new terminal, and call pod again.

# ~/.zshrc  (use the folder gem environment showed)
export PATH="$HOME/.gem/ruby/3.3.0/bin:$PATH"

3Verify

pod resolves to a path and prints its version.

which pod
pod --version

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 2 of 3

A Ruby version manager is using a different Ruby than the one that installed the gem

1Check

rbenv picks the version from RBENV_VERSION, then a .ruby-version file in the project, then the global version, and it only works when its shims directory is first on PATH.

rbenv version
rbenv versions
cat .ruby-version 2>/dev/null

2Fix

Install CocoaPods under the Ruby you actually use, or switch to the Ruby that already has it. Run rbenv rehash only if the shim is still missing.

rbenv global 3.3.5   # example version; pick one from rbenv versions
gem install cocoapods

3Verify

The pod shim exists and answers.

which pod
pod --version

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The install used sudo or a custom install directory, so the executable went elsewhere

1Check

RubyGems puts executables in the directory named by --bindir, and installs into GEM_HOME unless --install-dir or --user-install says otherwise. gem environment prints the real locations.

gem environment

2Fix

Reinstall to the default location, or add the executable directory to PATH. Run the executable by its full path once to prove it works (the CocoaPods guide gives this as the fallback).

gem install cocoapods
gem environment   # find the executable directory, then run its pod --version

3Verify

After the PATH change plain pod prints a version.

pod --version

Confirmed by guides.rubygems.org

Did this fix it?

How do I stop it coming back?

  • Use a Ruby you manage (rbenv or Homebrew) instead of the macOS system Ruby, as the CocoaPods guide suggests.
  • Put the PATH line in ~/.zshrc, and open a new terminal after changing it.
  • Pin the Ruby version per project with a .ruby-version file, which rbenv reads.

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?

Related fixes

Mobile apps

App record creation fails because you lack permission

You cannot add a new app in App Store Connect as a Developer or limited user

Only the Account Holder, an Admin or an App Manager can create an app record, and Apple blocks it until the Account Holder has signed the latest agreement.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.