Maaz Zindani

Loading the index…

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

pod install says 'You cannot run CocoaPods as root'

Error[!] You cannot run CocoaPods as root.

Short answer

CocoaPods has refused to run as root since version 0.32.0, because root-owned files can leave it in a broken state. Run pod without sudo. If an earlier sudo run left root-owned caches or a Pods folder, delete them and install again. On a CI container where root is unavoidable, pass --allow-root.

  • Applies to CocoaPods 1.16, macOS 15, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check who the shell runs as and who owns the CocoaPods cache and the Pods folder.

    whoami
    ls -ld ~/Library/Caches/CocoaPods Pods
  2. 2Match what you see, then jump to its fix

    1. 1[!] You cannot run CocoaPods as root.You ran pod with sudoFix
    2. 2Permission denied errors for files in the cache, the specs repo or Pods/ after you stopped using sudo.An earlier sudo run left root-owned filesFix
    3. 3The error appears in a pipeline where there is no other user.A CI job or Docker container runs everything as rootFix

What does the error look like?

  • [!] You cannot run CocoaPods as root.

Cause 1 of 3

You ran pod with sudo

1Check

Look at the command you typed. A sudo in front of pod install triggers the refusal.

whoami

2Fix

Run the same command as your normal user, without sudo.

pod install

3Verify

pod install finishes and creates the workspace.

ls -d *.xcworkspace

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 2 of 3

An earlier sudo run left root-owned files

1Check

If files are owned by root, your normal user cannot rewrite them.

ls -ld ~/Library/Caches/CocoaPods ~/.cocoapods/repos/master Pods

2Fix

The CocoaPods troubleshooting guide says to delete the root-owned cache and repo, then the Pods folder if errors remain, and install again as your user.

sudo rm -fr ~/Library/Caches/CocoaPods/
sudo rm -fr ~/.cocoapods/repos/master/
sudo rm -fr Pods/
pod install

3Verify

Files created by the new run belong to your user.

ls -ld Pods

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 3 of 3

A CI job or Docker container runs everything as root

1Check

In a container the default user is often root. Confirm with whoami in the job log.

whoami

2Fix

Either run the job as a normal user, or pass the --allow-root flag added in CocoaPods 1.10.0.

pod install --allow-root

3Verify

The job passes the install step.

pod --version

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Never put sudo in front of pod. Only the gem install step may need elevated rights, and a Ruby version manager removes that need.
  • In CI, create an unprivileged user in the image and run the build as that user.

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

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 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.