How to Fix 'zsh: command not found: pod' Error on macOS Catalina 10.15 After CocoaPods Installation

If you’re an iOS or macOS developer, you’ve likely encountered CocoaPods—the popular dependency manager for Swift and Objective-C projects. However, macOS Catalina (10.15) introduced changes that can trip up even experienced developers, especially with the switch from bash to zsh as the default shell. A common frustration is seeing the error zsh: command not found: pod after installing CocoaPods, even though you followed the official installation steps.

This guide will demystify why this error occurs and walk you through step-by-step solutions to resolve it. By the end, you’ll have pod recognized in your zsh terminal, allowing you to manage dependencies seamlessly.

Table of Contents#

  1. Why Does This Error Occur?
  2. Prerequisites
  3. Step-by-Step Solutions
  4. Verify the Fix
  5. Troubleshooting Common Issues
  6. Conclusion
  7. References

Why Does This Error Occur?#

The zsh: command not found: pod error arises because the zsh shell cannot locate the pod executable, even though CocoaPods is installed. Here’s why this happens on macOS Catalina:

1. zsh vs. bash: Different Configuration Files#

macOS Catalina replaced bash with zsh as the default shell. Unlike bash (which uses .bash_profile or .bashrc), zsh relies on .zshrc for environment variables like PATH. If CocoaPods is installed to a directory not listed in zsh’s PATH, the shell won’t find pod.

2. RubyGems Installation Paths#

CocoaPods is installed via RubyGems (gem install cocoapods). By default, RubyGems installs executables (like pod) to a "bin" directory specific to your Ruby version (e.g., /Users/yourname/.gem/ruby/2.6.0/bin). If this directory isn’t in zsh’s PATH, pod remains invisible.

3. macOS Catalina Restrictions#

macOS Catalina enforces System Integrity Protection (SIP), which limits write access to system directories. This means installing gems with sudo (e.g., sudo gem install cocoapods) may place pod in restricted locations (e.g., /usr/bin) that zsh can’t access without proper configuration.

4. Outdated or Misconfigured Ruby#

macOS Catalina ships with Ruby 2.6.3 (system Ruby), but it’s often outdated. If you installed Ruby via Homebrew or version managers like rbenv, the gem path may differ from the system default, leading to PATH mismatches.

Prerequisites#

Before proceeding, ensure you have the following:

  • macOS Catalina 10.15 (this guide is tailored to this version).
  • Xcode Command Line Tools: Install via xcode-select --install (required for CocoaPods and Ruby).
  • Ruby Installed: Either the system Ruby (preinstalled) or a newer version (via Homebrew, recommended).
  • CocoaPods Installed: You should have run gem install cocoapods (even if pod isn’t working yet).
  • Basic Terminal Skills: Familiarity with navigating the terminal and editing text files (e.g., with nano or vim).

Step-by-Step Solutions#

We’ll cover three methods to fix the error, starting with the simplest and progressing to more robust solutions.

Method 1: Add the Gem Bin Directory to zsh PATH#

The most common fix is to explicitly add the RubyGems "bin" directory to zsh’s PATH. Here’s how:

Step 1: Find Your RubyGems Executable Directory#

First, identify where RubyGems installs executables (like pod). Run this command in terminal:

gem environment | grep "EXECUTABLE DIRECTORY"

Example Output:

EXECUTABLE DIRECTORY: /Users/yourname/.gem/ruby/2.6.0/bin

Save this path (e.g., /Users/yourname/.gem/ruby/2.6.0/bin)—we’ll need it next.

Step 2: Edit ~/.zshrc to Add the Path#

zsh reads ~/.zshrc on startup, so we’ll add the gem bin directory to PATH here.

  1. Open ~/.zshrc in a text editor (we’ll use nano for simplicity):

    nano ~/.zshrc

  2. Add the following line at the bottom, replacing yourname and 2.6.0 with your actual path from Step 1:

    export PATH="$HOME/.gem/ruby/2.6.0/bin:$PATH"

    Note: Use $HOME instead of /Users/yourname for portability (it resolves to your home directory).

Step 3: Apply the Changes#

Save the file and exit nano:

  • Press Ctrl + O to save.
  • Press Enter to confirm the filename.
  • Press Ctrl + X to exit.

Then, reload ~/.zshrc to apply the new PATH:

source ~/.zshrc

Method 2: Reinstall CocoaPods Without sudo#

If you used sudo gem install cocoapods initially, you may have installed pod to a restricted system directory. Reinstalling without sudo places it in your user directory (safer and easier to manage).

Step 1: Uninstall Existing CocoaPods#

First, remove the old installation:

sudo gem uninstall cocoapods

Step 2: Reinstall CocoaPods to Your User Directory#

Install CocoaPods locally (no sudo) to avoid system directory issues:

gem install cocoapods --user-install

RubyGems will now install pod to your user-specific gem directory (e.g., ~/.gem/ruby/2.6.0/bin).

Step 3: Add the User Gem Directory to PATH#

Follow Step 2 and 3 from Method 1 to add this user-specific bin directory to ~/.zshrc.

System Ruby (2.6.3) is outdated and often causes gem path issues. Installing Ruby via Homebrew ensures a newer version and predictable paths.

Step 1: Install Homebrew (if not installed)#

Homebrew is a package manager for macOS. Install it with:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2: Install Ruby via Homebrew#

brew install ruby

Homebrew installs Ruby to /usr/local/opt/ruby (Intel Macs) or /opt/homebrew/opt/ruby (Apple Silicon, though Catalina is Intel-only).

Step 3: Add Homebrew Ruby to PATH#

Homebrew Ruby’s bin directory must be in PATH for zsh to find gems. Add this to ~/.zshrc:

For Intel Macs:

export PATH="/usr/local/opt/ruby/bin:$PATH"

(Catalina users: This is the correct path.)

Step 4: Install CocoaPods with Homebrew Ruby#

Now install CocoaPods using the Homebrew-managed Ruby:

gem install cocoapods

Homebrew Ruby’s gem bin directory (/usr/local/lib/ruby/gems/3.2.0/bin, for example) is automatically added to PATH, so pod should now be recognized.

Verify the Fix#

To confirm pod is working, run:

pod --version

If successful, you’ll see the CocoaPods version (e.g., 1.14.3).

Troubleshooting Common Issues#

Issue: .zshrc Doesn’t Exist#

If ~/.zshrc is missing, create it:

touch ~/.zshrc

Issue: pod Still Not Found After Adding PATH#

  • Check PATH: Run echo $PATH to confirm your gem bin directory is listed.
  • Verify pod Exists: Check if the pod executable exists in your gem bin directory: 
    ls /Users/yourname/.gem/ruby/2.6.0/bin/pod  # Replace with your path
    If missing, reinstall CocoaPods: gem install cocoapods.

Issue: Permission Errors When Editing .zshrc#

Ensure you own ~/.zshrc:

chown yourname:staff ~/.zshrc  # Replace "yourname" with your username

Issue: Outdated RubyGems#

Update RubyGems to avoid installation bugs:

gem update --system

Conclusion#

The zsh: command not found: pod error in macOS Catalina is almost always due to zsh not recognizing the path to the pod executable. By adding the RubyGems bin directory to zsh’s PATH, reinstalling CocoaPods without sudo, or using Homebrew Ruby, you can resolve this quickly.

For long-term stability, we recommend Method 3 (Homebrew Ruby), as it avoids system Ruby limitations and simplifies path management.

References#

2026-01