Ruby version mismatches and permission problems cause most CocoaPods install failures. Here is how to diagnose command-not-found and gem errors and get pod working reliably.
CocoaPods is a Ruby gem, so almost every install problem traces back to Ruby. The macOS system Ruby, gem permissions, and version incompatibilities are the usual culprits.
The two symptoms you will most often see are pod: command not found after installing, and a wall of red errors during gem install cocoapods. They look different but share root causes.
The good news is these are well-trodden problems. Once you understand where Ruby and its gems live on your machine, the fixes become straightforward.
This guide walks through diagnosis first, then the most reliable fixes, ending with the cleanest long-term setup.
Start by running ruby --version and which ruby. This tells you which Ruby is active and where it lives.
If the path points inside /usr/bin, you are using the system Ruby that ships with macOS. That Ruby is owned by the operating system, which is why installing gems into it often needs sudo and causes permission friction.
Also run gem environment to see where gems get installed and where their executables land. That executable directory is what needs to be on your PATH.
With these three pieces of information, most CocoaPods install mysteries resolve quickly. The fix usually comes down to permissions or PATH.
If gem install cocoapods succeeded but running pod says command not found, the gem's executable directory is not on your PATH.
Look at the GEM PATHS and executable directory from gem environment. The pod binary lives in a bin folder under that path.
Add that bin directory to your PATH in your shell profile, such as .zshrc for the default macOS shell. Then open a new Terminal window or reload the profile so the change takes effect.
Run pod --version again. Seeing a version confirms the command is now discoverable. This PATH issue is especially common when using a version manager or a non-default gem location.
If gem install cocoapods fails with permission denied errors while trying to write into system directories, you are hitting the system Ruby permission wall.
The quick workaround is sudo gem install cocoapods, which grants the write access. It works, but installing gems as root into system Ruby is fragile and can break with macOS updates.
A better quick fix is to install into your user gem directory instead, using gem install cocoapods --user-install, then ensuring that user gem bin directory is on your PATH.
The cleanest fix, however, is to stop using system Ruby altogether, which the next section covers.
Installing a separate, user-owned Ruby with a version manager such as rbenv eliminates the entire class of permission problems. You own that Ruby, so no sudo is ever needed.
Install the version manager, use it to install a recent stable Ruby, and set that Ruby as your default. Then run gem install cocoapods with no sudo at all.
Because the gems live in your home directory, permission errors simply disappear. Version conflicts also become manageable, since you can switch Ruby versions per project.
This setup takes a few extra minutes up front but saves hours of recurring frustration. It is the approach most experienced iOS developers recommend.
Sometimes gem install fails or CocoaPods misbehaves because the active Ruby is too old for the CocoaPods version being installed. Newer CocoaPods releases require reasonably modern Ruby.
Check the active Ruby version, and if it is the aging system Ruby, install a newer one via your version manager as described above.
After switching, reinstall CocoaPods against the new Ruby, since gems are tied to the specific Ruby they were installed under. A gem installed under one Ruby is not visible to another.
Confirm everything lines up by running which ruby, ruby --version, and pod --version together. All three should reflect your intended, modern setup.
Once pod --version works, run pod install in a real project to confirm the full pipeline functions, not just the command itself.
To prevent future breakage, pin your Ruby version for the project. A version manager can read a project file that records the exact Ruby version, keeping your whole team consistent.
Document your setup steps in the project README. New contributors hitting the same install wall will get unblocked without re-discovering every fix.
Remember these errors are environment issues, not problems with your app code. Solving them once, properly, means you rarely revisit them.
Some gems that CocoaPods depends on include native extensions that must compile during installation. If those fail, you will see errors mentioning a build or make step rather than CocoaPods itself.
The most common root cause is missing or mismatched Xcode command line tools. Reinstalling them with xcode-select --install, and making sure the active Xcode is selected, often clears these failures.
An outdated system Ruby can also struggle to build modern native extensions. This is another reason a user-owned Ruby from a version manager tends to be smoother.
After addressing the toolchain, retry the install cleanly. If a single dependency still refuses to build, read its specific error text, since the failing gem usually names exactly what header or tool it could not find.
If problems persist, fully uninstall conflicting CocoaPods installations and reinstall cleanly under a single, known Ruby. Mixed installs across system and user Ruby cause confusing behavior.
Check that your Xcode command line tools are installed and that Xcode has been opened once to accept its license, since some CocoaPods operations depend on them.
Search the exact error text against the official CocoaPods troubleshooting guide and its GitHub issues. Because CocoaPods is so widely used, most specific errors are already documented.
Finally, keep perspective: fixing the Ruby toolchain gets CocoaPods running, but you still build your app in Xcode and need the Apple Developer Program to ship it.
Most command not found and permission errors trace back to installing CocoaPods against the macOS system Ruby.
The system Ruby is owned by macOS, so gem install often needs sudo and can place binaries outside your PATH. That combination produces both permission failures and a CLI the shell cannot find afterward.
The durable fix is to install a separate Ruby with a version manager such as rbenv or rvm, or via Homebrew, and point your shell at it.
With a user-owned Ruby you install the CocoaPods gem without sudo, and its bin directory is on your PATH by default. After switching, restart your terminal and run pod --version to confirm the shell resolves the new binary.
The gem installed successfully, but the directory containing the pod executable is not on your PATH. Run gem environment to find the executable directory, add it to your shell profile such as .zshrc, then open a new terminal and try again.
sudo gem install cocoapods works but installs into the system Ruby as root, which is fragile and can break with macOS updates. A cleaner approach is installing a user-owned Ruby with a version manager like rbenv, then running gem install cocoapods without sudo.
They come from trying to write into the system Ruby directories. Either use gem install cocoapods --user-install and add the user gem bin to your PATH, or better, install a separate Ruby with a version manager so no elevated permissions are ever needed.
Install a newer, stable Ruby with a version manager, set it as your default, then reinstall CocoaPods under that Ruby. Gems are tied to the specific Ruby they were installed under, so you must reinstall after switching.
No. Install and gem errors are environment and toolchain issues, not problems with your Swift or Objective-C. Fixing your Ruby setup once, ideally with a version manager, resolves them for good.