Using sudo gem install cocoapods on macOS can lead to permission issues and dependency conflicts. More importantly, this method ties CocoaPods to the system’s Ruby version, which can break after macOS updates.
A better approach is to install CocoaPods independently in your user directory, ensuring stability, flexibility, and the ability to manage multiple versions.
Step 1: Check Your gem Version:
First, check if your gem version is up to date (2.6.14 or higher is recommended):
gem --version
2、Step 2: Upgrade gem if Needed
If your gem version is outdated, upgrade it:
sudo gem update --system
Step 3: Change gem Source (Optional, for Faster Downloads in China)
If you’re in China, switching to a local gem source can speed up downloads:
sudo gem --remove https://rubygems.org
sudo gem --add http://gems.ruby-china.org
4、Use the Sudo-less(without sudo) install method to install CocoaPods:
a)、Create a new directory in your Home directory, such as Vendor/ruby
mkdir -p $HOME/Vendor/ruby
b)、Set environment variables to define the installation path:
export GEM_HOME=$HOME/Vendor/ruby
export PATH=$HOME/Vendor/ruby/bin:$PATH
c)、Install CocoaPods (e.g., version 1.15):
gem install cocoapods -v 1.15
5、Step 5: Make the Environment Variables Persistent
To ensure the setup remains effective after restarting your Mac, add the environment variables to your shell configuration file.
For Intel Macs / older macOS versions:
source ~/.bash_profile
For Apple Silicon (M1/M2) Macs:
source ~/.zshrc
Files related to CocoaPods that are installed using the above method will be installed in the Vendor/ruby directory under your home directory.
Step 6: Verify the Installation
Run the following command to check if CocoaPods was installed successfully:
pod --version
if it return 1.15, the installation was successful.
Why Install CocoaPods Independently?
✅ No system Ruby dependencies – macOS updates won’t break CocoaPods
✅ Easier version management – use different CocoaPods versions for different projects
✅ No sudo required – improves security and avoids permission issues
✅ Portable setup – easily migrate your environment by copying the Vendor/ruby directory
By installing CocoaPods independently, you gain full control over its versioning and avoid potential issues caused by system updates. This method is highly recommended for macOS developers looking for a stable, flexible, and hassle-free CocoaPods installation.